Configuration

LayerFileConfig

LayerFileConfig

Type: object

Main 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" ```

No Additional Properties

Type: boolean or null

Controls whether or not mirrord accepts invalid TLS certificates (e.g. self-signed certificates).


Agent configuration, see [agent::AgentFileConfig].

Type: object

Configuration for the mirrord-agent pod that is spawned in the Kubernetes cluster.

No Additional Properties

Type: integer or nullFormat: uint16

Controls 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.

Type: boolean or null

Runs the agent as an ephemeral container

Type: boolean or null

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.

Type: string or null

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.

Type: string or null

Controls when a new agent image is downloaded.

Supports any valid kubernetes image pull policy

Type: string or null

Log level for the agent.

Supports anything that would work with RUST_LOG.

Type: string or null

Namespace where the agent shall live.

Defaults to the current kubernetes namespace.

Type: string or null

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.

Type: boolean or null

Controls target pause feature. Unstable.

With this feature enabled, the remote container is paused while clients are connected to the agent.

Type: integer or nullFormat: uint64

Controls how long to wait for the agent to finish initialization.

If initialization takes longer than this value, mirrord exits.

Type: integer or nullFormat: uint16

Controls how long the agent pod persists for after the agent exits (in seconds).

Can be useful for collecting logs.

Type: null

Type: string or null

Agent name that already exists that we can connect to.

Type: integer or nullFormat: uint16

Agent listen port that already exists that we can connect to.

Type: string or null

IP:PORT to connect to instead of using k8s api, for testing purposes.


Controls mirrord features, see [feature::FeatureFileConfig].

Type: object

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 .txt files), 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 ```

No Additional Properties

Type: boolean or null

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.

Type: object

Type: object

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" ```

No Additional Properties


Include the remote environment variables in the local process that are NOT specified by this option.

Value is a list separated by ";".

Type: object or null

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: string


Controls the file operations feature, see [FsConfig].

For more information, check the file operations technical reference.

Type: object

Type: object

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"] ```

Type: object

Basic configuration that controls the env vars MIRRORD_FILE_OPS and MIRRORD_FILE_RO_OPS (default).

Type: enum (of string)

mirrord won't do anything fs-related, all operations will be local.

Must be one of:

  • "local"
Type: enum (of string)

mirrord will run overrides on some file operations, but most will be local.

Must be one of:

  • "localwithoverrides"
Type: enum (of string)

mirrord will read files from the remote, but won't write to them.

Must be one of:

  • "read"
Type: enum (of string)

mirrord will read/write from the remote.

Must be one of:

  • "write"
Type: object

Allows the user to specify both [FsModeConfig] (as above), and configuration for the overrides.

No Additional Properties


File operations mode, defaults to read-only, see [FsModeConfig].

Type: object

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 ```

Same definition as feature_anyOf_i0_fs_anyOf_i0_anyOf_i1_anyOf_i0


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.


Controls the network feature, see [NetworkConfig].

For more information, check the network traffic technical reference.

Type: object

Type: object

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 ```

No Additional Properties

Type: boolean or null

Resolve DNS via the remote pod.


Handles incoming network traffic, see [IncomingConfig] for more details.

Type: object

Type: object

Controls the incoming TCP traffic feature.

See the incoming reference for more details.

Incoming traffic supports 2 modes of operation:

  1. Mirror (default): Sniffs the TCP data from a port, and forwards a copy to the interested listeners;

  2. 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.*" ```


Type: object

Mode of operation for the incoming TCP traffic feature.

Defaults to [IncomingMode::Mirror].

Type: enum (of string)

Sniffs on TCP port, and send a copy of the data to listeners.

Must be one of:

  • "mirror"
Type: enum (of string)

Stealer supports 2 modes of operation:

  1. 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);

  2. 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"
Type: object


Sets up the HTTP traffic filter (currently, only for [IncomingMode::Steal]).

See [HttpHeaderFilterConfig] for details.

Type: object

Type: object

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.

No Additional Properties

Type: string or null

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.

Type: object

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.

Type: boolean or null

Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702

Type: array of array or null

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:

Type: array

Must contain a minimum of 2 items

Must contain a maximum of 2 items

Tuple Validation

Item at 1 must be:
Item at 2 must be:
Type: null

Type: string or null

Path to a kubeconfig file, if not specified, will use KUBECONFIG or ~/.kube/config or the in-cluster config.

Type: boolean or null

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};

Type: object

Specifies the target to mirror. See [Target].

Examples

  • Mirror pod hello-world-abcd-1234 in the hello namespace:

```toml # mirrord-config.toml

[target] path = "pod/hello-world-abcd-1234" namespace = "hello" ```


Type: object

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" ```

Type: object

Mirror a deployment.

Type: string

Deployment to mirror.

Type: object

Mirror a pod.

Type: string

Pod to mirror.

Type: object

Type: string or null

Default: null

Type: object

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" ```

Same definition as target_anyOf_i0_anyOf_i0_anyOf_i0
Type: null