> For the complete documentation index, see [llms.txt](https://docs.fluentbit.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fluentbit.io/manual/data-pipeline/inputs/forward.md). # Forward {% hint style="info" %} **Supported event types:** `logs` `metrics` `traces` {% endhint %} *Forward* is the protocol used by [Fluent Bit](https://fluentbit.io) and [Fluentd](https://www.fluentd.org) to route messages between peers. This plugin implements the input service to listen for Forward messages. ## Configuration parameters The plugin supports the following configuration parameters: | Key | Description | Default | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `buffer_chunk_size` | By default the buffer to store the incoming Forward messages, don't allocate the maximum memory allowed, instead it allocate memory when it's required. The rounds of allocations are set by `buffer_chunk_size`. The value must be according to the [Unit Size](/manual/administration/configuring-fluent-bit.md#unit-sizes) specification. | `1024000` | | `buffer_max_size` | Specify the maximum buffer memory size used to receive a Forward message. This limit also applies to incoming payloads and decompressed data; payloads exceeding this size are rejected and the connection is closed. The value must be according to the [Unit Size](/manual/administration/configuring-fluent-bit.md#unit-sizes) specification. | `6144000` | | `empty_shared_key` | Enable secure forward protocol with a zero-length shared key. Use this to enable user authentication without requiring a shared key, or to connect to Fluentd with a zero-length shared key. | `false` | | `listen` | Listener network interface. | `0.0.0.0` | | `msgpack_memory_limit` | In v5.1.4 or later, sets the maximum memory used to decode the MessagePack data of an incoming Forward message, including the entries of `PackedForward` payloads. If a message exceeds this limit, the plugin logs the warning `invalid frame or MessagePack allocation budget exceeded` and closes the connection. A value of `0` sets the limit to 16 times `buffer_max_size`, with a minimum of 64 KiB. The value must be according to the [Unit Size](/manual/administration/configuring-fluent-bit.md#unit-sizes) specification. | `0` | | `port` | TCP port to listen for incoming connections. | `24224` | | `security.users` | Specify the username and password pairs for secure forward authentication. Requires `shared_key` or `empty_shared_key` to be set. | *none* | | `self_hostname` | Hostname for secure forward authentication. | `localhost` | | `shared_key` | Shared key for secure forward authentication. | *none* | | `signal_object_memory_limit` | In v5.1.5 or later, sets the estimated maximum memory used to decode the metrics or traces in an incoming `PackedForward` or `CompressedPackedForward` message. For `CompressedPackedForward` messages, the limit applies to the decompressed data. Each top-level MessagePack object, array element, and map entry counts as 1024 bytes, so this is an estimate, not an exact memory limit. If a message exceeds this limit, the plugin logs the warning `PackedForward signal object budget exceeded or invalid payload` and closes the connection. This limit is independent of `msgpack_memory_limit`. The value must be at least 1024 bytes and must be according to the [Unit Size](/manual/administration/configuring-fluent-bit.md#unit-sizes) specification. | `100M` | | `tag` | Override the tag of the forwarded events with the defined value. In v5.1.3 or later, if `tag` and `tag_prefix` aren't set and an incoming tag is empty, the input name is used. If `tag_prefix` is set, it's applied to the incoming tag instead. | *none* | | `tag_prefix` | Prefix incoming tag with the defined value. | *none* | | `threaded` | Indicates whether to run this input in its own [thread](/manual/administration/multithreading.md#inputs). | `false` | | `unix_path` | Specify the path to Unix socket to receive a Forward message. If set, `listen` and `port` are ignored. | *none* | | `unix_perm` | Set the permissions of the Unix socket file as an octal value. If not set, the permissions depend on the file mode creation mask of the Fluent Bit process. If `unix_path` isn't set, this parameter is ignored. See [Unix socket files](#unix-socket-files). | *none* | | `workers` | The number of listener workers that accept and process incoming connections. Not supported with `unix_path`; a value greater than `1` while `unix_path` is set causes startup to fail. | `1` | ### Payload validation In v5.1.3 or later, the plugin validates `PackedForward` and `CompressedPackedForward` payloads before it ingests them. If an entry isn't a valid log event, the plugin logs the warning `invalid PackedForward entry` and rejects the payload. ### Unix socket files When `unix_path` is set, Fluent Bit checks the path before it creates the socket: * In v5.2 or later, if `unix_path` is longer than the operating system allows for a Unix socket path, which is 107 bytes on Linux and 103 bytes on macOS, startup fails with `configured unix socket path is too long`. Earlier versions silently truncated the path. * If a Unix socket already exists at `unix_path`, Fluent Bit removes it and creates a new one, even if another process is still listening on it. If Fluent Bit can't check or remove the existing file, startup fails with `could not remove existing unix socket . Aborting`. * If anything else exists at `unix_path`, startup fails with ` exists and it is not a unix socket. Aborting`. In v5.2 or later, this includes any symbolic link, even one that points to a socket. Earlier versions followed symbolic links, so a link to a socket was replaced with a new socket. If `unix_path` is a symbolic link, point `unix_path` at a regular location before you upgrade. In v5.2 or later, when `unix_perm` is set, Fluent Bit creates the socket in a temporary directory named `.fb-` followed by six random characters, in the same directory as `unix_path`. It sets the socket permissions to `unix_perm`, renames the socket to `unix_path`, and removes the temporary directory. The socket never appears at `unix_path` with other permissions. If Fluent Bit stops during this step, the temporary directory can remain and is safe to delete. If Fluent Bit can't create the directory or set the permissions, startup fails with a `could not create staging directory` or `cannot set permission on` error. Fluent Bit reads `unix_perm` as an octal number and ignores everything from the first character that isn't an octal digit, without logging an error. For example, `rw-r--r--` results in permissions `0000`. A leading `+` or `-` sign is also accepted and the result is masked to `07777`, so `-1` results in `07777`, which lets every local user write to the socket. Use an unsigned octal value such as `0660`. ### TLS / SSL The Forward input plugin supports TLS/SSL. For more details about the properties available and general configuration, refer to [Transport Security](/manual/administration/transport-security.md). ## Get started To receive Forward messages, you can run the plugin from the command line or through the configuration file as shown in the following examples. ### Command line From the command line you can let Fluent Bit listen for Forward messages with the following options: ```shell fluent-bit -i forward -o stdout ``` By default, the service listens on all interfaces (`0.0.0.0`) through TCP port `24224`. You can change this by passing parameters to the command: ```shell fluent-bit -i forward -p listen="192.168.3.2" -p port=9090 -o stdout ``` In the example, the Forward messages arrive only through network interface `192.168.3.2` address and TCP Port `9090`. ### Configuration file In your main configuration file append the following: {% tabs %} {% tab title="fluent-bit.yaml" %} ```yaml pipeline: inputs: - name: forward listen: 0.0.0.0 port: 24224 buffer_chunk_size: 1M buffer_max_size: 6M outputs: - name: stdout match: '*' ``` {% endtab %} {% tab title="fluent-bit.conf" %} ``` [INPUT] Name forward Listen 0.0.0.0 Port 24224 Buffer_Chunk_Size 1M Buffer_Max_Size 6M [OUTPUT] Name stdout Match * ``` {% endtab %} {% endtabs %} ## Fluent Bit and secure forward setup In Fluent Bit v3 or later, `in_forward` can handle secure forward protocol. {% hint style="warning" %} When using `security.users` for user-password authentication, you **must** also configure either `shared_key` or set `empty_shared_key` to `true`. The Forward input plugin will reject a configuration that has `security.users` set without one of these options. {% endhint %} For shared key authentication, specify `shared_key` in both forward output and forward input. For user-password authentication, specify `security.users` with at least one user-password pair along with a shared key. To use user authentication without requiring clients to know a shared key, set `empty_shared_key` to `true`. The `self_hostname` value can't be the same between Fluent Bit servers and clients. {% tabs %} {% tab title="fluent-bit-secure-forward.yaml" %} ```yaml pipeline: inputs: - name: forward listen: 0.0.0.0 port: 24224 buffer_chunk_size: 1M buffer_max_size: 6M security.users: fluentbit changeme shared_key: secret self_hostname: flb.server.local outputs: - name: stdout match: '*' ``` {% endtab %} {% tab title="fluent-bit-secure-forward.conf" %} ``` [INPUT] Name forward Listen 0.0.0.0 Port 24224 Buffer_Chunk_Size 1M Buffer_Max_Size 6M Security.Users fluentbit changeme Shared_Key secret Self_Hostname flb.server.local [OUTPUT] Name stdout Match * ``` {% endtab %} {% endtabs %} ### User authentication with `empty_shared_key` To use username and password authentication without requiring clients to know a shared key, set `empty_shared_key` to `true`: {% tabs %} {% tab title="fluent-bit-user-auth.yaml" %} ```yaml pipeline: inputs: - name: forward listen: 0.0.0.0 port: 24224 buffer_chunk_size: 1M buffer_max_size: 6M security.users: fluentbit changeme empty_shared_key: true self_hostname: flb.server.local outputs: - name: stdout match: '*' ``` {% endtab %} {% tab title="fluent-bit-user-auth.conf" %} ``` [INPUT] Name forward Listen 0.0.0.0 Port 24224 Buffer_Chunk_Size 1M Buffer_Max_Size 6M Security.Users fluentbit changeme Empty_Shared_Key true Self_Hostname flb.server.local [OUTPUT] Name stdout Match * ``` {% endtab %} {% endtabs %} ## Testing After Fluent Bit is running, you can send some messages using the `fluent-cat` tool, provided by [Fluentd](https://www.fluentd.org): ```shell echo '{"key 1": 123456789, "key 2": "abcdefg"}' | fluent-cat my_tag ``` When you run the plugin with the following command: ```shell fluent-bit -i forward -o stdout ``` In [Fluent Bit](https://fluentbit.io) you should see the following output: ``` ... [0] my_tag: [1475898594, {"key 1"=>123456789, "key 2"=>"abcdefg"}] ... ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.fluentbit.io/manual/data-pipeline/inputs/forward.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.