# SFTP (prebuilt connector)

## Description

The Patchworks SFTP connector is used to connect SFTP servers, for use in process flows.  

## Authentication 

When adding connector instances for the Patchworks SFTP connector, the following authentication methods are supported:

* [SFTP User Pass (username & password)](#sftp-user-pass)
* [SFTP Key Pass (private & public key files)](#sftp-key-pass)

Guidance for using these authentication methods is summarised below.

{% hint style="warning" %}
If you are using a custom version of our prebuilt SFTP connector (i.e. if the authentication method and/or endpoint settings have been updated after the original installation), please be aware that your settings and requirements may vary.
{% endhint %}

### User pass

The Patchworks SFTP connector supports authentication via username/password. If you choose to [add a connector instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) with **user pass** authentication, you need to enter the following details:  

<table><thead><tr><th width="240">Credential</th><th>Notes</th></tr></thead><tbody><tr><td><code>Host</code></td><td>Enter the host name provided by your SFTP provider. For example: <code>eu-west-1.sftpcloud.io</code></td></tr><tr><td><code>Username</code></td><td>Enter the username provided by your SFTP provider. </td></tr><tr><td><code>Password</code></td><td>Enter the password provided by your SFTP provider. </td></tr><tr><td><code>Port</code></td><td>Enter the port number provided by your SFTP provider. </td></tr><tr><td><code>Root</code></td><td>Enter the initial directory that the SFTP client connects to once a connection is made. This becomes the reference point for subsequent file operations. For example: <code>/</code></td></tr><tr><td><code>Path</code></td><td>Specify a location of specific files or directories relative to the root that you wish to use, or leave blank.<br><br><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line"> Whenever the <a href="/pages/SavR9CxDNdGwueoGB3Ac">SFTP connector is added to a process flow</a>, you need to enter the required <code>path</code> to be accessed. With this in mind, there's no need to be too specific when setting up the instance - entering <code>/</code> here is fine.</td></tr><tr><td><code>Visibility</code></td><td><p>Refers to file visibility - set to <code>public</code> or <code>private</code>. The default setting of <code>public</code> is typical however, set to <code>private</code> if your SFTP server requires. </p><p></p><p><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line"> Private visibility is where an SFTP server does not list files within directories - which means you have to know the exact name of any file(s) that you want to target.</p></td></tr><tr><td><code>Directory visibility</code></td><td><p>Set to <code>public</code> or <code>private</code>. The default setting of <code>public</code> is typical however, set to <code>private</code> if your SFTP server requires. </p><p></p><p><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line"> Private directory visibility is where an SFTP server does not list directories from the root - which means you have to know the exact name of any directory that you want to target.</p></td></tr><tr><td><code>Max tries</code></td><td>Enter the maximum number of connection attempts that should be made before the connection is determined to have have failed.</td></tr><tr><td><code>Timeout</code></td><td>Enter the maximum number of seconds that the connector should wait for a response from the SFTP server before it determines the connection attempt to be failed.</td></tr></tbody></table>

### Key pass

The Patchworks SFTP connector supports authentication via public/private keys. If you choose to [add a connector instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) with **key pass** authentication, you need to enter the following details: &#x20;

<table><thead><tr><th width="240">Credential</th><th>Notes</th></tr></thead><tbody><tr><td><code>Host</code></td><td>Enter the host name provided by your SFTP provider. For example: <code>eu-west-1.sftpcloud.io</code></td></tr><tr><td><code>Username</code></td><td>Enter the username provided by your SFTP provider. </td></tr><tr><td><code>Port</code></td><td>Enter the port number provided by your SFTP provider. </td></tr><tr><td><code>Private key</code></td><td><p>Copy/paste in the private key for this connection. The key should be pasted in full - for example:  </p><pre><code>-----BEGIN PRIVATE KEY-----
MHc123456fNphsKI77lw/CaRA4v93oAoGCP4tchI5ac4t49
123UQDQgAE6i6U/g&#x26;KLD23456789ZBs0OWXOg5NJ7XAFxAwIJf78FJR2ORUI
x+G2KPR123456789mkfAQP9FYg==
-----END PRIVATE KEY-----
</code></pre><p>Currently, RSA (<code>.pem</code>) format must be used. If your key is in a different format, you can convert it using tools such as <a href="https://www.puttygen.com/">PuttyGen</a>.</p></td></tr><tr><td><code>Passphrase</code></td><td>If you added a passphrase when generating public/private keys for this connection, enter it here.</td></tr><tr><td><code>Host fingerprint</code></td><td>This is an optional security measure, normally used to ensure that the server you are connecting to is not an imposter - it aims to mitigate threats such as 'man in the middle' attacks. Here, an MD5 or SHA512 fingerprint can be used. <br><br><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line">Fingerprints are tied to the hashing algorithm used to generate the public key - the default is often (but not always) MD5. For more information please see the <a href="#generating-host-fingerprint-values">Generating host fingerprint values</a> section below.</td></tr><tr><td><code>Root</code></td><td>Enter the initial directory that the FTP client connects to once a connection is made. This becomes the reference point for subsequent file operations. For example: <code>/</code></td></tr><tr><td><code>Path</code></td><td>Specify a location of specific files or directories relative to the root that you wish to use, or leave blank.<br><br><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line"> Whenever the <a href="/pages/SavR9CxDNdGwueoGB3Ac">SFTP connector is added to a process flow</a>, you need to enter the required <code>path</code> to be accessed. With this in mind, there's no need to be too specific when setting up the instance - entering <code>/</code> here is fine.</td></tr><tr><td><code>Visibility</code></td><td><p>Refers to file visibility - set to <code>public</code> or <code>private</code>. The default setting of <code>public</code> is typical however, set to <code>private</code> if your SFTP server requires. </p><p></p><p><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line"> Private visibility is where an SFTP server does not list files within directories - which means you have to know the exact name of any file(s) that you want to target.</p></td></tr><tr><td><code>Directory visibility</code></td><td><p>Set to <code>public</code> or <code>private</code>. The default setting of <code>public</code> is typical however, set to <code>private</code> if your SFTP server requires. </p><p></p><p><img src="/files/SQLJTyh7dnCup0hVzTVb" alt="" data-size="line"> Private directory visibility is where an SFTP server does not list directories from the root - which means you have to know the exact name of any directory that you want to target.</p></td></tr><tr><td><code>Max tries</code></td><td>Enter the maximum number of connection attempts that should be made before the connection is determined to have have failed.</td></tr><tr><td><code>Timeout</code></td><td>Enter the maximum number of seconds that the connector should wait for a response from the SFTP server before it determines the connection attempt to be failed.</td></tr></tbody></table>

## Generating host fingerprint values

Server finger prints are created using the FTP server’s **public key**. The server will provide this in either **SSH-RSA** or **SSH-SHA** format. Patchworks chooses the most secure **public key** format available on the FTP server for fingerprint verification, noting that:&#x20;

* The **public key** must be Base64 decoded and then hashed with either **md5** or **sha512** algorithms.
* The preferred key format is **ssh-ed25519** but **ssh-rsa** format is acceptable.&#x20;

The steps below summarise how to generate a host server fingerprint:

**Step 1**\
Assuming that your **public key** is stored on your FTP server, you can use the following OpenSSH command to scan the available public key and save it to a local file:&#x20;

```
ssh-keyscan [Host Address]> [local filename]
```

{% hint style="info" %}
More information about OpenSSH command can be find here: <https://www.openssh.com>.
{% endhint %}

**Step 2**\
Open the file - it should display the key with its hostname and key format - for example:

<figure><img src="/files/EPxlveEc1emZlfctepCn" alt=""><figcaption></figcaption></figure>

**Step 3**\
To generate your `host server fingerprint` you will need to copy the key, decode it and then hash it with either the **md5** or **sha512** algorithm. You can do this with <https://onlinephp.io/> using the code snippet below:

{% code lineNumbers="true" %}

```php
<?php
//$publicKey = [YOUR PUBLIC KEY];
$publicKey = 'ssh-ed25519 YOUR_PUBLIC_KEY_HERE';
$content = explode(' ', $publicKey);
$algo = $content[0] === 'ssh-rsa' ? 'md5' : 'sha512';
echo implode(':', str_split(hash($algo, base64_decode($content[1])), 2));
```

{% endcode %}

Here, you should replace the `YOUR_PUBLIC_KEY_HERE` placeholder in line 3 with your own public key, then execute the code to generate a fingerprint value:&#x20;

<figure><img src="/files/O5T90sCJ20yjYdLOZvj3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The fingerprint is generated in either **md5** or **sha51** format, depending on whether the first element of the `$content` array (line 4) is **ssh-rsa**. If it is, the hash algorithm is set to md5 - otherwise, it's set to sha512.
{% endhint %}

## Troubleshooting SFTP connections

If an error is given when you try to save [connector instance settings](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md), check that:

* Your credentials are valid
* The associated user has permissions to access the specified root and path directories on the FTP server&#x20;

It's a good idea to try the same settings in an FTP client - if they work there, they should work when creating a Patchworks instance.&#x20;

## More information

For further information about working with the SFTP connector please see our [Configuring SFTP connections](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape/configuring-sftp-connections.md) page.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/patchworks-connectors/sftp-prebuilt-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.