Xferity Configuration — YAML-Driven MFT Setup with Strict Validation

Configuration

Xferity uses configuration files to define global runtime behavior, partner endpoints, and transfer flows.

The configuration model is intended to keep transfer behavior reviewable and repeatable. Instead of embedding decisions in scripts, operators define them in YAML.

Configuration layers

Most deployments work with three layers:

global configuration
partner configuration
flow configuration

For production operation, configuration should also be understood alongside managed crypto Assets, bindings, and backend selection.

Global configuration

The global config controls runtime-wide behavior such as:

flows and partners paths
storage base path
state backend selection
worker settings
logging and audit behavior
UI and API behavior
authentication settings
secret-provider configuration
notification defaults

Partner configuration

Partner files define reusable endpoint settings for:

SFTP
FTPS
S3-compatible storage
AS2
local filesystem endpoints

This separates reusable connection and trust settings from flow-specific scheduling and file rules.

Partner definitions are also where transport trust and partner-facing crypto expectations are anchored.

Flow configuration

Flow files define the actual transfer workflow: direction, file matching, scheduling, idempotency, cleanup, payload handling, and endpoint usage.

Flow configuration should be read together with Flow Crypto Requirements and runtime validation behavior.

Managed crypto Assets

For production operation, managed crypto Assets are preferable to ad hoc crypto material embedded directly into flow YAML.

The platform manages two Asset types:

Certificate
PGP Key

Those Assets can then be bound into partner roles and used by flows through the product’s policy and runtime resolution paths.

OpenPGP provider modes

Xferity supports three OpenPGP execution modes in flow pgp configuration:

gopenpgp — use the native Go OpenPGP path only
gnupg — use GnuPG only
auto — try the native path once, then try GnuPG once only when the native error is classified as a supported compatibility case

Example:

pgp:
  provider: auto
  gnupg_binary: /usr/bin/gpg

If provider=gnupg or provider=auto, startup validation requires GnuPG to be available on the host.

When fallback can happen

Fallback is intentionally narrow.

auto fallback is allowed only when the native provider reports a classified compatibility case:

compat_enterprise_key_structure

This is used for keys that are valid in enterprise environments and supported by GnuPG, but not handled consistently by the native provider.

Fallback does not happen for general failures such as:

missing files
missing keys
wrong passphrase
bad signatures
generic permission or path errors

Enterprise key structure

compat_enterprise_key_structure means the key layout is compatible with real enterprise OpenPGP usage, but may include details the native library does not handle reliably.

Examples include:

signing-capable key resolution failure
primary key stub or offline primary key layout
partial secret-key export structure

This is the named compatibility scenario used for Workday-style partner cases.

Validation behavior

Configuration parsing is intentionally strict.

The YAML loader rejects unknown fields, which means misspelled keys fail validation instead of being silently ignored.

This is important for MFT systems because silent configuration drift is a common failure mode in script-based deployments.

Environment placeholder expansion

Global and flow config support environment placeholder expansion such as:

${VAR}
${VAR:-default}

This allows environment-specific values without maintaining separate file structures for minor differences.

Defaults

The loader applies defaults for several settings, including:

state.backend=file
Postgres sslmode=require
worker polling and timeout values
flow idempotency mode
SFTP retry and timeout defaults
audit sidecar and chain-state path defaults
HTTP rate-limit defaults

Defaults help startup, but they should still be reviewed before production use.

Secret references

Sensitive values should use secret references rather than plaintext values.

The resolver supports:

environment references
file references
local encrypted secret storage in supported Postgres-backed deployments
Vault
AWS Secrets Manager
Azure Key Vault

Some bootstrap values must still come from bootstrap-safe sources such as env or file references.

Partner Crypto Policy and Flow Crypto Requirements

Two product concepts matter when reading configuration:

Partner Crypto Policy describes what crypto roles are configured and bound for a partner
Flow Crypto Requirements describe what crypto roles are required by a flow at run time

These are not just UI labels. They are part of the operational model used by validation and runtime preflight.

Hardened mode implications

When hardened mode is enabled, the runtime rejects several insecure patterns, including plaintext secrets in expected sensitive fields and insecure Postgres or provider settings.

This is configuration enforcement, not a replacement for operational secret management.

State backend configuration

One of the most important settings is state.backend.

File-backed mode

Use file-backed mode for simpler single-node operation with local state files.

This mode is suitable for evaluation and smaller deployments. It provides local state and basic runtime behavior. Advanced control-plane features — sessions, crypto inventory, suppressions, posture snapshots, regression alerts — are limited or unavailable.

Postgres-backed mode

Use Postgres-backed mode when you need queued jobs, worker execution, sessions, certificate records, AS2 persistence, or local encrypted secret storage.

When state.backend=postgres, a DSN or equivalent connection fields are required.

Postgres is the required backend for the full posture engine, suppression records, regression alerts, shared job queue, and operator UI with session-backed authentication.

Backend capability summary

Capability	File-backed runtime	Postgres-backed runtime
local state and history	supported	supported
auth and sessions	limited	full
crypto inventory	limited	full
suppressions	not supported	supported
posture snapshots	not supported	supported
regression alerts	not supported	supported
worker-driven durable jobs	limited	supported

Partner validation rules

Partner files are validated against protocol-specific rules. Examples include:

partner id must match the filename
SFTP known_hosts must be a file: reference when used in partner config
SFTP fingerprints must start with SHA256:
FTPS is limited to explicit TLS mode and passive mode
AS2 receipt mode must be sync or async
hardened mode rejects insecure TLS skip-verify partner settings

Flow defaults and behavior

Flow config defaults include:

idempotency_mode=hash
lock wait and stale-lock values
per-flow parallelism defaults
SFTP retry defaults
SFTP timeout and remote stability defaults

Minimal flows can run with a small number of fields, but production flows should be reviewed field by field.

Recommended workflow

For production use, a reasonable configuration workflow is:

keep config, partner files, and flow files under version control
use secret references rather than plaintext values
run validation before rollout
run diagnostics before enabling schedules
review hardened mode early
document runtime paths and retention behavior