> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-7-0/connectors/shop-floor-connectors/file/fileconnection.md).

# File Connection Properties

## `transport` (object, required)

Where the files are and how the connector reaches them. `type` selects the transport. Properties that do not apply to the selected transport are rejected unless they are set to their default value.

Properties of the `transport` object:

#### `type` (string, enum, required)

Transport to the files. `local` reads a directory inside the Protocol Mapper or agent container, including SMB/CIFS and NFS shares mounted into it. `sftp` connects to an SFTP server and supports every mode. `ftp` connects to an FTP or FTPS server in passive mode and supports only `batch` mode.

This element must be one of the following enum values:

* `local`
* `sftp`
* `ftp`

Example: `"sftp"`

#### `basePath` (string)

Required for the `local` transport. Absolute directory inside the container that contains all files of this connection, usually the mount point of a share. It must be inside one of the directories in the `CYBUS_FILE_LOCAL_ROOTS` environment variable of the Protocol Mapper or agent, which defaults to `/mnt`. Endpoint `path` and `afterProcessing.moveTo` values must be inside `basePath`, and relative values resolve against it. Symbolic links inside `basePath` are followed only when their target is also inside `basePath`. Links that point outside it are refused with `EPATHESCAPE` and left out of directory listings.

Example: `"/mnt/line3"`

#### `host` (string)

Hostname or IP address of the SFTP or FTP server. Required for the `sftp` and `ftp` transports.

Example: `"10.0.0.5"`

#### `port` (integer)

TCP port of the server. Defaults to 22 for `sftp` and 21 for `ftp`, also with `tls: implicit`. Implicit FTPS servers usually listen on port 990, so set the port explicitly.

Example: `22`

Additional restrictions:

* Minimum: `1`
* Maximum: `65535`

#### `username` (string)

Login name. Required for `sftp`. For `ftp`, leave it out to log in anonymously.

Example: `"line3"`

#### `password` (string)

Password for the server. For `sftp`, set `password`, `privateKey`, or both. If both are set, the password is tried first. The value is masked in API responses.

#### `privateKey` (string)

SFTP only. SSH private key (RSA or Ed25519) in PEM format, as text or Base64-encoded. If `password` is set as well, the password is tried first. The value is masked in API responses.

#### `passphrase` (string)

SFTP only. Passphrase that decrypts an encrypted `privateKey`. Leave unset for unencrypted keys.

#### `knownHosts` (array)

SFTP only. Host keys the server may present. Each entry is either a fingerprint `SHA256:<base64>`, which is the second field of the `ssh-keygen -lf` output, or a public-key line `<key-type> <base64>` as in `~/.ssh/known_hosts`, where a leading host name is ignored. Required with `hostKeyVerification: strict`. With `trustOnFirstUse`, these keys are accepted in addition to the learned key.

The object is an array with all elements of the type `string`.

Example: `["SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s"]`

Additional restrictions:

* Minimum items: `1`

#### `hostKeyVerification` (string, enum)

SFTP only. How the connector checks the host key of the server. `strict` accepts only keys listed in `knownHosts`. `trustOnFirstUse` saves the key of the first successful connection and logs its SHA256 fingerprint, then accepts only that key or keys in `knownHosts`. Use it when you cannot get the key in advance. `insecure` accepts any key and logs a warning on every connection. Use it only for testing. If `knownHosts` is set, `insecure` still checks against it.

This element must be one of the following enum values:

* `strict`
* `trustOnFirstUse`
* `insecure`

Default: `"strict"`

#### `hostKeyGeneration` (integer)

SFTP only, with `hostKeyVerification: trustOnFirstUse`. Counter that resets the learned host key. Increase it to forget the key, for example after the server was reinstalled or the connection points to a different server. The next connection learns the new key.

Default: `0`

#### `tls` (string, enum)

FTP only. `none` uses plain FTP, `explicit` upgrades the control connection with AUTH TLS after connecting (FTPES, usually port 21), `implicit` expects TLS from the first byte (usually port 990).

This element must be one of the following enum values:

* `none`
* `explicit`
* `implicit`

Default: `"none"`

#### `tlsRejectUnauthorized` (boolean)

FTP only. If `true`, the FTPS server certificate must be signed by a trusted CA. To trust a self-signed or internal certificate, add it to `tlsCa`. Set this to `false` only for testing.

Default: `true`

#### `tlsCa` (string)

FTP only. PEM-encoded CA certificates for verifying the FTPS server certificate. When set, only these certificates are trusted, instead of the default CA list.

## `pollIntervalMs` (integer)

Pause in milliseconds between two checks of the file or directory of an endpoint. All transports are polled. There is no change notification.

Default: `1000`

Example: `1000`

Additional restrictions:

* Minimum: `100`

## `operationTimeoutMs` (integer)

Maximum time in milliseconds for one operation on the server or file system. If checking a file, listing a directory, or reading a file times out, the connection is marked as lost and reconnects. If moving or deleting a file after processing times out, the error is logged and the connection stays up.

Default: `30000`

Additional restrictions:

* Minimum: `1000`

## `probeIntervalMs` (integer)

Interval in milliseconds at which the connector checks that the server or `basePath` is reachable. If the check fails, the connection switches to `reconnecting`.

Default: `10000`

Additional restrictions:

* Minimum: `1000`

## `connectionStrategy` (object)

Configuration for retrying failed connection attempts using an exponential backoff strategy.

Properties of the `connectionStrategy` object:

#### `initialDelay` (integer)

Delay (in milliseconds) before the first retry attempt after a failed connection.

Default: `1000`

Additional restrictions:

* Minimum: `1000`

#### `maxDelay` (integer)

Maximum delay (in milliseconds) between retry attempts.

Default: `30000`

#### `incrementFactor` (integer)

Multiplier applied to the previous delay to calculate the next retry delay, up to 'maxDelay'.

Default: `2`

Additional restrictions:

* Minimum: `2`


---

# 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.cybus.io/2-7-0/connectors/shop-floor-connectors/file/fileconnection.md?ask=<question>&goal=<user_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.
