Configuration
LayerFileConfig
Type: objectMain struct for mirrord-layer's configuration
Examples
- Run mirrord with read-only file operations, mirroring traffic, skipping unwanted processes:
```toml # mirrord-config.toml
target = "pod/sample-pod-1234" skip_processes = ["ide-debugger", "ide-service"] # we don't want mirrord to hook into these
[agent] log_level = "debug" ttl = 1024 # seconds
[feature] fs = "read" # default
[feature.network] incoming = "mirror" # default ```
- Run mirrord with read-write file operations, stealing traffic, accept local TLS certificates, use a custom mirrord-agent image:
```toml # mirrord-config.toml
target = "pod/sample-pod-1234" acceptinvalidcertificates = true
[agent] loglevel = "trace" ttl = 1024 # seconds image = "registry/mirrord-agent-custom:latest" imagepull_policy = "Always"
[feature] fs = "write"
[feature.network] incoming = "steal" ```
Controls whether or not mirrord accepts invalid TLS certificates (e.g. self-signed certificates).
Agent configuration, see [agent::AgentFileConfig].
Configuration for the mirrord-agent pod that is spawned in the Kubernetes cluster.
No Additional PropertiesControls how long the agent lives when there are no connections.
Each connection has its own heartbeat mechanism, so even if the local application has no messages, the agent stays alive until there are no more heartbeat messages.
Flushes existing connections when starting to steal, might fix issues where connections aren't stolen (due to being already established)
Temporary fix for issue #1029.
Name of the agent's docker image.
Useful when a custom build of mirrord-agent is required, or when using an internal registry.
Defaults to the latest stable image.
Controls when a new agent image is downloaded.
Supports any valid kubernetes image pull policy
Log level for the agent.
Supports anything that would work with RUST_LOG.
Namespace where the agent shall live.
Defaults to the current kubernetes namespace.
Which network interface to use for mirroring.
The default behavior is try to access the internet and use that interface and if that fails it uses eth0.
Controls target pause feature. Unstable.
With this feature enabled, the remote container is paused while clients are connected to the agent.
Controls how long to wait for the agent to finish initialization.
If initialization takes longer than this value, mirrord exits.
Controls how long the agent pod persists for after the agent exits (in seconds).
Can be useful for collecting logs.
Agent name that already exists that we can connect to.
Agent listen port that already exists that we can connect to.
IP:PORT to connect to instead of using k8s api, for testing purposes.
Controls mirrord features, see [feature::FeatureFileConfig].
Configuration for mirrord features.
For more information, check the technical reference of the feature.
Examples
- Exclude "SECRET" environment variable, enable read-write file operations, mirror network traffic (default option), and generate a crash report (if there is any crash):
```toml # mirrord-config.toml
[feature] fs = "write" captureerrortrace = true
[feature.env] exclude = "SECRET" ```
- Include only "DATABASE_URL", and "PORT" environment variables, enable read-write file operations (only for
.txtfiles), and enable both incoming and outgoing network traffic (mirror):
```toml # mirrord-config.toml
[feature.env] include = "DATABASE_URL;PORT"
[feature.fs] mode = "write" include = "^.*.txt$"
[feature.network] incoming = "mirror" # default, included here for effect
[feature.network.outgoing] tcp = true udp = true ```
Controls the crash reporting feature.
With this feature enabled, mirrord generates a nice crash report log.
Controls the environment variables feature, see [EnvConfig].
For more information, check the environment variables technical reference.
Allows the user to set or override a local process' environment variables with the ones from a remote pod.
Which environment variables to load from the remote pod are controlled by setting either include or exclude.
See the environment variables reference for more details.
Examples
- Include every environment variable from the remote pod (default):
```toml # mirrord-config.toml
[feature.env] include = "*" ```
Some environment variables are excluded by default (PATH for example), including these requires specifying them with include, see mirrord-agent::env::EnvFilter.
- Include the remote pod's environment variables "PROJECT", "DATABASE":
```toml # mirrord-config.toml
[feature.env] include = "PROJECT;DATABASE" ```
- Exclude the remote pod's environment variables "USER", "SECRET", and include everything else:
```toml # mirrord-config.toml
[feature.env] exclude = "USER;SECRET" ```
Include the remote environment variables in the local process that are NOT specified by this option.
Value is a list separated by ";".
Each item of this array must be:
Include only these remote environment variables in the local process.
Value is a list separated by ";".
Allows setting or overriding environment variables (locally) with a custom value.
For example, if the remote pod has an environment variable REGION=1, but this is an undesirable value, it's possible to use overrides to set REGION=2 (locally) instead.
Each additional property must conform to the following schema
Type: stringControls the file operations feature, see [FsConfig].
For more information, check the file operations technical reference.
Changes file operations behavior based on user configuration.
Defaults to [FsUserConfig::Simple], with [FsModeConfig::Read].
See the file operations reference for more details.
Examples
- Read-write file operations:
```toml # mirrord-config.toml
[feature] fs = "write" ``- Read/liblocally,/etcremotely and/var/run` read write remotely. Rest local
```yaml # mirrord-config.yaml
[fs] mode = read readwrite = ["/var/run"] readonly = ["/etc"] local = ["/lib"] ```
Basic configuration that controls the env vars MIRRORD_FILE_OPS and MIRRORD_FILE_RO_OPS (default).
mirrord won't do anything fs-related, all operations will be local.
Must be one of:
- "local"
mirrord will run overrides on some file operations, but most will be local.
Must be one of:
- "localwithoverrides"
mirrord will read files from the remote, but won't write to them.
Must be one of:
- "read"
mirrord will read/write from the remote.
Must be one of:
- "write"
Allows the user to specify both [FsModeConfig] (as above), and configuration for the overrides.
Specify file path patterns that if matched will be opened locally.
File operations mode, defaults to read-only, see [FsModeConfig].
Configuration for enabling read-only and read-write file operations. These options are overriden by user specified overrides and mirrord default overrides. If you set LocalWithOverrides then somefiles can be read/write remotely based on our default/user specified. Default option for general file configuration.
Examples
- Disable mirrord file operations:
```yaml # mirrord-config.yaml
fs = local ```
- Enable mirrord read-write file operations:
```yaml # mirrord-config.yaml
fs = write ```
Specify file path patterns that if matched will be read from the remote. if file matching the pattern is opened for writing or read/write it will be opened locally.
Specify file path patterns that if matched will be read and written to the remote.
Controls the network feature, see [NetworkConfig].
For more information, check the network traffic technical reference.
Controls mirrord network operations.
See the network traffic reference for more details.
Examples
- Steal incoming traffic, enable TCP outgoing traffic and DNS resolution:
```toml # mirrord-config.toml
[feature.network] incoming = "steal" dns = true # not needed, as this is the default
[feature.network.outgoing] tcp = true ```
Resolve DNS via the remote pod.
Handles incoming network traffic, see [IncomingConfig] for more details.
Controls the incoming TCP traffic feature.
See the incoming reference for more details.
Incoming traffic supports 2 modes of operation:
Mirror (default): Sniffs the TCP data from a port, and forwards a copy to the interested listeners;
Steal: Captures the TCP data from a port, and forwards it (depending on how it's configured, see [
IncomingMode::Steal]);
Examples
- Mirror any incoming traffic:
```toml # mirrord-config.toml
[feature.network] incoming = "mirror" # for illustration purporses, it's the default ```
- Steal incoming HTTP traffic, if the HTTP header matches "Id: token.*" (supports regex):
```yaml # mirrord-config.yaml
[feature.network.incoming] mode = "steal"
[feature.network.incoming.httpheaderfilter] filter = "Id: token.*" ```
Mode of operation for the incoming TCP traffic feature.
Defaults to [IncomingMode::Mirror].
Sniffs on TCP port, and send a copy of the data to listeners.
Must be one of:
- "mirror"
Stealer supports 2 modes of operation:
Port traffic stealing: Steals all TCP data from a port, which is selected whenever the user listens in a TCP socket (enabling the feature is enough to make this work, no additional configuration is needed);
HTTP traffic stealing: Steals only HTTP traffic, mirrord tries to detect if the incoming data on a port is HTTP (in a best-effort kind of way, not guaranteed to be HTTP), and steals the traffic on the port if it is HTTP;
Must be one of:
- "steal"
Sets up the HTTP traffic filter (currently, only for [IncomingMode::Steal]).
See [HttpHeaderFilterConfig] for details.
Filter configuration for the HTTP traffic stealer feature.
Allows the user to set a filter (regex) for the HTTP headers, so that the stealer traffic feature only captures HTTP requests that match the specified filter, forwarding unmatched requests to their original destinations.
Only does something when IncomingConfig is set as IncomingMode::Steal, ignored otherwise.
Used to match against the requests captured by the mirrord-agent pod.
Supports regexes validated by the fancy-regex crate.
Usage
The HTTP traffic feature converts the HTTP headers to HeaderKey: HeaderValue, case-insensitive.
Activate the HTTP traffic filter only for these ports.
Helper struct for setting up ports configuration (part of the HTTP traffic stealer feature).
Defaults to a list of ports [80, 8080].
Internal
We use this to allow implementing a custom [Default] initialization, as the [MirrordConfig] macro (currently) doesn't support more intricate expressions.
Value must be greater or equal to 0.0
Each item of this array must be:
Value must be greater or equal to 0.0
Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702
Allows selecting between mirrorring or stealing traffic.
See [IncomingMode] for details.
Mode of operation for the incoming TCP traffic feature.
Defaults to [IncomingMode::Mirror].
Mapping for local ports to remote ports.
This is useful when you want to mirror/steal a port to a different port on the remote machine. For example, your local process listens on port 9333 and the container listens on port 80. You'd use [[9333, 80]]
Each item of this array must be:
Must contain a minimum of 2 items
Must contain a maximum of 2 items
Tuple Validation
Item at 1 must be:
Value must be greater or equal to 0.0
Item at 2 must be:
Value must be greater or equal to 0.0
Tunnel outgoing network operations through mirrord.
No Additional Properties
Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702
Path to a kubeconfig file, if not specified, will use KUBECONFIG or ~/.kube/config or the in-cluster config.
Allow to lookup if operator is installed on cluster and use it
Binaries to patch (macOS SIP). Use this when mirrord isn't loaded to protected binaries that weren't automatically patched. Runs endswith on the binary path (so bash would apply to any binary ending with bash while /usr/bin/bash would apply only for that binary).
Allows mirrord to skip unwanted processes.
Useful when process A spawns process B, and the user wants mirrord to operate only on process B.
Specifies the running pod to mirror.
Supports: - pod/{sample-pod}/[container]/{sample-container}; - podname/{sample-pod}/[container]/{sample-container}; - deployment/{sample-deployment}/[container]/{sample-container};
Specifies the target to mirror. See [Target].
Examples
- Mirror pod
hello-world-abcd-1234in thehellonamespace:
```toml # mirrord-config.toml
[target] path = "pod/hello-world-abcd-1234" namespace = "hello" ```
Specifies the running pod (or deployment) to mirror.
Supports: - pod/{sample-pod}; - podname/{sample-pod}; - deployment/{sample-deployment}; - container/{sample-container}; - containername/{sample-container}.
Examples
- Mirror pod
hello-world-abcd-1234:
```toml # mirrord-config.toml
target = "pod/hello-world-abcd-1234" ```
Mirror a deployment.
Deployment to mirror.
Mirror a pod.
Pod to mirror.
Specifies the running pod (or deployment) to mirror.
Supports: - pod/{sample-pod}; - podname/{sample-pod}; - deployment/{sample-deployment}; - container/{sample-container}; - containername/{sample-container}.
Examples
- Mirror pod
hello-world-abcd-1234:
```toml # mirrord-config.toml
target = "pod/hello-world-abcd-1234" ```