Configure() — URL + payload setup

Every remote client object exposes a Configure() method that sets up the connection in one call by accepting a URL and an optional JSON payload string. This mirrors the configuration style used by VirtualFS objects and is the recommended approach when connection details are stored in secrets or arrive as configuration strings.

IMPORTANT

Configure() is available as of Syncplify Server! v7.0.17. The field-by-field approach described in Client constructors and connection fields is still fully supported and will never be removed.

---

How it works

var cli = new SftpClient();
cli.Configure("sftp://alice@sftp.example.com", GetSecret("sftp-payload-json"));
if (cli.Connect()) {
  // ...
  cli.Close();
}

Configure() returns the client object itself, so the call can be chained:

var cli = new SftpClient()
  .Configure("sftp://alice@sftp.example.com", GetSecret("sftp-payload-json"));

What goes in the URL vs. the payload

Info type	Where to put it
Host, port, bucket name, container name, region	URL (non-sensitive, fine in plain text)
Credentials (passwords, keys, tokens, secrets)	Payload JSON (store in a secret)
Transfer options (overwrite policy, OTFE, versioning)	Payload JSON

---

SFTP: Configure(url, payload?)

var cli = new SftpClient().Configure(
  "sftp://alice@sftp.example.com:22?hostKeySHA256=SHA256:AAAA...",
  GetSecret("sftp-payload")
);

URL format

sftp://[user[:pass]@]host[:port][?query]

Default port: 22

Query parameter	Description
hostKeyMD5	MD5 host-key fingerprint (32 hex chars, colons optional)
hostKeySHA1	SHA-1 host-key fingerprint
hostKeySHA256	SHA-256 host-key fingerprint (recommended)
keyFile	Path to an SSH private-key file on disk
keyFilePass	Passphrase for the key file
hostID	Freeform label used in log messages

NOTE

Embedding a password in the URL is allowed for convenience but discouraged in production. Prefer storing the password in the JSON payload as pass (via the payload private_key / private_key_pass fields), or using key-based auth.

SFTP payload fields

JSON key	Type	Description
private_key	string	PEM content of an SSH private key. When set, keyFile is ignored.
private_key_pass	string	Passphrase to decrypt private_key.
host_key_md5	string	MD5 host-key fingerprint (overrides URL query value).
host_key_sha1	string	SHA-1 host-key fingerprint (overrides URL query value).
host_key_sha256	string	SHA-256 host-key fingerprint (overrides URL query value).
(shared fields)		See shared payload fields below.

Example payload JSON:

{
  "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----",
  "host_key_sha256": "SHA256:AAAA...",
  "upload_policy": 1
}

---

FTP / FTPS: Configure(url, payload?)

var cli = new FtpsClient().Configure(
  "ftpes://alice@ftp.example.com",
  GetSecret("ftp-payload")
);

URL format

ftp://host[:port]     → plain FTP (TLSMode 0)
ftpes://host[:port]   → Explicit FTPS / AUTH TLS (TLSMode 1)
ftps://host[:port]    → Implicit FTPS (TLSMode 2)

Default port: 21 for ftp:// and ftpes://, 990 for ftps://

Query parameter	Description
insecure=true	Skip TLS certificate verification — only for controlled internal environments

FTPS payload fields

JSON key	Type	Description
(shared fields)		See shared payload fields below.

The FTPS payload carries only shared transfer-policy fields; the TLS mode and host come from the URL. Store the password directly in the URL (for convenience) or set FtpsClient.Pass manually after Configure() for better security.

---

Amazon S3 / S3-compatible: Configure(url, payload?)

var cli = new S3Client().Configure(
  "s3://my-bucket?region=us-east-1",
  GetSecret("s3-payload")
);

URL format

s3://bucket[/keyPrefix][?query]

Query parameter	Description
region	AWS region (e.g. us-east-1)
endpoint	Custom endpoint URL (MinIO, Wasabi, Backblaze B2, …)
pathStyle=true	Force path-style addressing (required by most S3-compatible services)

S3 payload fields

JSON key	Type	Description
access_key	string	IAM access key ID
access_secret	string	IAM secret access key
region	string	AWS region (overrides URL query value)
endpoint	string	Custom endpoint URL (overrides URL query value)
encryption_pass	string	Passphrase for at-rest encryption (SSE-C)
upload_concurrency	int	Number of parallel multipart upload threads
download_concurrency	int	Number of parallel multipart download threads
(shared fields)		See shared payload fields below.

Example payload JSON:

{
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "access_secret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "upload_policy": 3,
  "otfe": true,
  "otfe_key": "my-encryption-passphrase"
}

TIP

When both access_key and access_secret are absent from the payload, the default AWS credential chain is used: environment variables, ~/.aws/credentials, EC2 instance role, etc.

---

Azure Blob Storage: Configure(url, payload?)

var cli = new AzureClient().Configure(
  "azblob://my-container",
  GetSecret("azure-payload")
);

URL format

azblob://container[/containerPath]
azblob://container@https://account.blob.core.windows.net/[/containerPath]

The host portion encodes the container name and optionally an endpoint, separated by @. The path portion sets a prefix within the container.

Azure payload fields

JSON key	Type	Description
account_name	string	Azure storage account name
account_key	string	Base64-encoded SharedKey credential
sas_token	string	Shared Access Signature token (alternative to account_key)
container_name	string	Container name (overrides the URL host value if set)
endpoint	string	Custom service URL (e.g. Azurite emulator or sovereign cloud)
encryption_pass	string	Passphrase for Customer-Provided Key (CPK) at-rest encryption
upload_concurrency	int	Number of parallel block upload threads
download_concurrency	int	Number of parallel block download threads
(shared fields)		See shared payload fields below.

Example payload JSON:

{
  "account_name": "mystorageaccount",
  "account_key": "dGVzdA==...",
  "upload_with_temp_name": true,
  "download_policy": 3
}

---

Google Cloud Storage: Configure(url, payload?)

var cli = new GCSClient().Configure(
  "gcs://my-bucket/reports",
  GetSecret("gcs-payload")
);

URL format

gcs://bucket[/prefix]

The path portion sets an optional key prefix (BucketPath).

GCS payload fields

JSON key	Type	Description
project_id	string	GCP project identifier
bucket_name	string	Bucket name (overrides the URL host value if set)
bucket_path	string	Key prefix within the bucket (overrides the URL path if set)
credentials_file	string	Path to a service-account JSON key file
encryption_pass	string	Passphrase for client-side at-rest encryption
upload_concurrency	int	Number of parallel object upload threads
download_concurrency	int	Number of parallel object download threads
(shared fields)		See shared payload fields below.

TIP

When credentials_file is absent, application default credentials are used: GOOGLE_APPLICATION_CREDENTIALS env variable, GCE metadata server, or the gcloud CLI defaults.

---

Shared payload fields

These fields appear in every client's payload and map directly to the corresponding Options fields. See ClientOptions for detailed descriptions.

JSON key	Type	Default	Corresponding Options field
stop_on_error	bool	false	StopOnTransferError
download_policy	int	0 (NeverOverwrite)	DownloadPolicy
upload_policy	int	0 (NeverOverwrite)	UploadPolicy
on_download_grant_to	string	""	OnDownloadGrantTo
adjust_time_on_download	bool	true	AdjustTimeOnDownload
adjust_time_on_upload	bool	true	AdjustTimeOnUpload
download_with_temp_name	bool	false	DownloadWithTempName
upload_with_temp_name	bool	false	UploadWithTempName
delete_source_after_download	bool	false	DeleteSourceAfterDownload
delete_source_after_upload	bool	false	DeleteSourceAfterUpload
versioned_download	bool	false	VersionedDownload
versioned_upload	bool	false	VersionedUpload
versions_to_keep_local	int	3	VersionsToKeepLocal
versions_to_keep_remote	int	3	VersionsToKeepRemote
otfe	bool	false	OTFE
otfe_algorithm	int	0 (AES-256-GCM)	OTFEAlgorithm
otfe_key	string	""	OTFEKey
connect_timeout_seconds	int	30	ConnectTimeoutSeconds

NOTE

adjust_time_on_download and adjust_time_on_upload default to true. Omitting them from the payload preserves that default. Only include them when you explicitly want to change the value.

---

Mixing Configure() with field-by-field assignment

Configure() only sets the fields that are present in the URL or payload. Any field you do not include remains at its zero value (or at whatever you assigned previously). You can freely mix the two styles:

var cli = new SftpClient()
  .Configure("sftp://sftp.example.com?hostKeySHA256=SHA256:AAAA...");

// override one field after Configure()
cli.User = CurrentSession.GetUserName();

if (cli.Connect()) {
  cli.Download("/remote/inbox/*.csv", "/local/processing");
  cli.Close();
}

---

Using the same payload as VirtualFS

The payload JSON keys used here are intentionally identical to those used by the VirtualFS SFTP, S3, Azure, and GCS filesystem objects. If you already have a payload string stored as a secret for a VirtualFS configuration, you can pass it directly to the corresponding client's Configure() call without any modification.

// 'sftp-vfs-payload' was originally created for a VirtualFS SFTP filesystem —
// it works as-is with SftpClient.Configure()
var cli = new SftpClient()
  .Configure("sftp://sftp.example.com", GetSecret("sftp-vfs-payload"));