Documentation
¶
Overview ¶
Package csharg captures network traffic inside container hosts that are either stand-alone or part of a Kubernetes cluster. These are live captures: the captured network packets are immediately streamed to capture clients. There is no need to record first, and then download; instead, you can analyse network traffic live as it happens. So, Streaming Killed the Download Star – with apologies to Trevor Horn.
Live network captures can be taken not only from standalone containers, but also from Kubernetes pods, the node (host) network stacks, and even process-less standalone virtual network stacks.
Please note that due to the “sandbox” design of Kubernetes pods, it is not possible to capture from a single container inside a pod: all containers in the same pod share the same network stack.
Optionally, network captures can be confined to only a subset of network interfaces of a pod, container, et cetera. Furthermore, clients can specify packet filters to apply at the sources, before sending the capture stream. Please see struct CaptureOptions for details.
Normally, packet capture streaming will go on until you stop it. See the examples for how to automatically stop a packet capture stream after a given amount of time.
Index ¶
- Constants
- Variables
- func CaptureServiceHeaders(t *api.Target, opts *CaptureOptions) (header *http.Header, err error)
- func CaptureServiceQueryParams(t *api.Target, opts *CaptureOptions) (values *url.Values, err error)
- func CompleteTarget(t *api.Target, opts *CaptureOptions, ts *TargetCache) (*api.Target, error)
- type CaptureOptions
- type CaptureStreamer
- type CommonClientOptions
- type Nifs
- type SharkTank
- type SharkTankOnHostOptions
- type TargetCache
Constants ¶
const ( // DefaultServiceTimeout specifies the time limit for completing discovery // service calls and for establishing a stream connection to the capture // service. DefaultServiceTimeout = 30 * time.Second )
const SemVersion = "0.12.2-10-g6c9c830"
SemVersion is the semantic version string of the csharg module.
Variables ¶
var AllNifs = Nifs{}
AllNifs will capture from all available network interfaces of a capture target, regardless of how many and which ones it will have. This is just a convenience to those situations where a programmer wants to emphasize explicitly capturing from all network interfaces of a capture target, instead of the implicit zero default.
Functions ¶
func CaptureServiceHeaders ¶
CaptureServiceHeaders is a convenience function that builds the set of capture service HTTP/WS headers required in order to successfully connect via the Kubernetes remote API proxy to the capture service -- where the WS service request unfortunately looses the URL parameters, so we need to resort to HTTP headers. This bug is documented, but doesn't seem to get any attention to fix it, which really is unfortunate. Anyway, we use the capture service headers also when not passing broken Kubernetes remote API servers, to keep things more uniform.
func CaptureServiceQueryParams ¶
CaptureServiceQueryParams is a convenience function that builds the HTTP/WS URL query parameters necessary to connect successfully to the capture service -- unless there's a broken Kubernetes remote API proxy in between where we query params get lost in transit, but we uniformly use the query params whenever we contact the SharkTank capture service, regardless of the path we'll take.
func CompleteTarget ¶
func CompleteTarget(t *api.Target, opts *CaptureOptions, ts *TargetCache) (*api.Target, error)
CompleteTarget completes the capture target description to the point that the SharkTank service can be successfully contacted on the service application level. If the target description needs to be modified, then CompleteTarget will return a shallow copy of the passed target description, with the necessary additional data filled in. Otherwise, if the target description is already sufficient to start the capture, then it will be returned as-is instead.
Please note that any list of network interfaces in the capture target description will be replaced by either the list specified in the capture options (which takes precedence) or the discovered complete list of network interfaces for this target.
Types ¶
type CaptureOptions ¶
type CaptureOptions struct { // The list of network interfaces (names) to capture from; defaults to all // network interfaces of the capture target (that is, AllNifs) if left zero. Nifs Nifs // Packet capture filter expression, defaults to no filtering. For its // syntax, please refer to: // https://www.tcpdump.org/manpages/pcap-filter.7.html Filter string // If true, avoid switching into promiscuous mode if possible. Please note // that it is not possible to disable promiscuous mode: other parallel // captures might already have switched on promiscuous mode so we can never // force it off. This zero setting defaults to switching promiscuous mode // ON. AvoidPromiscuousMode bool }
CaptureOptions describe a set of options giving more detailed control over how to capture network traffic from a capture target and an optional specific set of network interfaces to capture from.
type CaptureStreamer ¶
type CaptureStreamer interface { // Stop this capture in an orderly manner. This operation will block until // the capture has finally terminated. It is also idempotent. Stop() // Wait for the capture to terminate, but do not initiate the termination. Wait() // StopAfter waits the specified duration for the capture to terminate, and // terminates it after the duration if necessary. StopAfter(d time.Duration) }
CaptureStreamer gives control over an individual network packet capture.
func StartCaptureStream ¶
func StartCaptureStream(w io.Writer, ws *websocket.Conn, t *api.Target, opts *CaptureOptions) (cs CaptureStreamer, err error)
StartCaptureStream is a low-level function almost all cshark package users WON'T use. Instead, csharg package users typically want to use the high-level SharkTank methods CapturePod, CaptureContainer, and Capture instead. Please see the package examples for how to use the high-level capture functions.
The low-level StartCaptureStream which needs to be given an already successfully connected websocket, a capture target specification, and capture options. It then starts the capture by issuing a capture service request via the websocket and then in the background streams the incomming network packet data into the given Writer.
type CommonClientOptions ¶
type CommonClientOptions struct { // BearerToken optionally specifies the bearer token to use when talking to // the cluster capture service, regardless of how we reach the service. BearerToken string // Timeout specifies a time limit for requests made to the SharkTank cluster // capture service. For discovery it limits the time allowed to complete a // discovery request and response. For capturing it limits just the // connection establishing phase, including the web socket handshake phase. Timeout time.Duration }
CommonClientOptions defines options common to all cluster capture client types.
type SharkTank ¶
type SharkTank interface { // Lists the available capture targets in this cluster. Targets() (ts api.Targets) // Captures network traffic from a specific pod and send the captured packet // stream to the writer w. The capture optionally can be restricted to only // a subset of the pod's network interfaces. The pod name can be prefixed by // a namespace in form of "namespace/podname"; if the namespace is left out // it defaults to the aptly-named "default" namespace. CapturePod(w io.Writer, podname string, opts *CaptureOptions) (cs CaptureStreamer, err error) // Captures network traffic from a specific container on a specific // kubernetes node. Of course, the capture can be restricted to only a // subset of the pod's network interfaces. CaptureContainer(w io.Writer, nodename, name string, opts *CaptureOptions) (cs CaptureStreamer, err error) // Captures network traffic from a capture target, such as a pod, a // stand-alone container, a process-less IP stack, et cetera, optionally // limited to a specific (set of) network interface(s) for this target. The // captured packets are then send to the given Writer. Capture(w io.Writer, t *api.Target, opts *CaptureOptions) (cs CaptureStreamer, err error) // Clears the cached set of capture targets: a SharkTank will fetch the set // of capture targets anew when it needs them, and will then cache them // because typically there will be multiple lookups into the cached set // necessary in order to start a capture. Clear() }
SharkTank gives access to network captures in clusters via the SharkTank cluster capture service.
func NewSharkTankOnHost ¶
func NewSharkTankOnHost(hosturl string, opts *SharkTankOnHostOptions) (st SharkTank, err error)
NewSharkTankOnHost returns a new host capturer object to capture directly from host targets using a Packetflix service, and accessing it via host+port and an optional service path.
type SharkTankOnHostOptions ¶
type SharkTankOnHostOptions struct { CommonClientOptions InsecureSkipVerify bool }
SharkTankOnHostOptions allows some degree of control over how to use a (SharkTank) Packetflix service reachable at a given address and port.
type TargetCache ¶
type TargetCache struct {
// contains filtered or unexported fields
}
TargetCache caches and indexes a set of capture targets. It can safely be accessed simultaneously by multiple go routines.
func (*TargetCache) Clear ¶
func (tc *TargetCache) Clear()
Clear the cached capture target descriptions.
func (*TargetCache) IsEmpty ¶
func (tc *TargetCache) IsEmpty() bool
IsEmpty returns true if the cache is empty, otherwise false.
func (*TargetCache) OnNode ¶
func (tc *TargetCache) OnNode(nodename, prefix, name string) (*api.Target, bool)
OnNode returns the capture target with the given prefix+name and located on the specified cluster node. Use OnNode() when capturing from per-node targets, such as a kubelet, et cetera. For capturing from pods, use Pod() instead, as it doesn't need the specific nodename to be told.
func (*TargetCache) Pod ¶
func (tc *TargetCache) Pod(name string) (*api.Target, bool)
Pod returns the pod capture target with the specified prefix and name. For other types of targets the lookup will fail and return (nil, false). Use OnNode() instead when looking up capture targets that may occur multiple times inside a cluster on different cluster nodes.
func (*TargetCache) Set ¶
func (tc *TargetCache) Set(ts api.Targets)
Set the target descriptions to be cached.
func (*TargetCache) Targets ¶
func (tc *TargetCache) Targets() api.Targets
Targets returns the list of capture target descriptions.
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
Package api defines the JSON data structures describing the available capture targets returned by the capture service endpoint(s).
|
Package api defines the JSON data structures describing the available capture targets returned by the capture service endpoint(s). |
Package cli defines plugin extension points for the csharg command.
|
Package cli defines plugin extension points for the csharg command. |
command
Package command implements the common commands of the csharg CLI.
|
Package command implements the common commands of the csharg CLI. |
cmd
|
|
internal
|
|
Package pcapng implements a pcapng stream editor which edits the first Section Header Block (SHB), inserting additional meta data as comments.
|
Package pcapng implements a pcapng stream editor which edits the first Section Header Block (SHB), inserting additional meta data as comments. |
Package pipe implements waiting for a fifo/pipe to break.
|
Package pipe implements waiting for a fifo/pipe to break. |
Package ws enhances Gorilla client websockets by handling graceful closing on both sides using polite close control messages.
|
Package ws enhances Gorilla client websockets by handling graceful closing on both sides using polite close control messages. |