# FreeMFT pilot 0.1.5

**Under active development — test environments only.** This pilot is for testing and evaluation. Do not use it in production.

Self-contained SFTP managed file transfer for **Linux x86-64**. The administrator configures accounts, receiving folders, SFTP destinations, custom scripts, and post-processing retention. Users have SFTP upload/download access only.

## Run the Linux bundle

```sh
tar -xzf freemft-0.1.5-linux-x86_64.tgz
cd freemft
./start.sh
```

Open **http://SERVER:8888**. Initial administrator credentials: **Free / MFT**. A new password of at least eight characters is required at first login. Change the administrator username/password later under **Administrator settings**.

Startup prints the configured listener, the machine hostname when it resolves to a listening interface, and all applicable local IPv4/IPv6 interface addresses. A restricted binding lists only matching addresses; firewall and DNS settings still determine remote reachability.

## New in 0.1.5: additional permissions

Overwrite existing files, list directory contents, move between folders, and set/preserve timestamps are separate permissions. All four start disabled, including for existing profiles on upgrade. See Additional permission behavior below.

## Features from 0.1.4 — action forms and exports/imports

- **Folder actions** shows settings relevant to the selected action. Choose a destination for SFTP forwarding or a script for script processing. Retry and timeout settings appear for forwarding and scripts.
- **Overview → Recent transfers** is a clickable heading that opens **Track Transfers**, with the current transfer history and fresh filters.
- **Activity log → Export full activity log (CSV)** downloads the complete history, including entries outside the current screen or text filter. Administrator sign-in is required. Exports include event details and script output; keep them private and avoid recording secrets in scripts.
- **Services & storage → Export settings & accounts** saves a configuration export in the application folder and provides an authenticated download link. The export includes administrator and account sign-in information, account paths, permission profiles, SFTP settings, destinations and their credentials, folder actions, ColdStorage settings, and the SFTP host identity when available. Existing administrator and account passwords continue to work after import.

### Import on a new or existing deployment

Stop FreeMFT on the target. Copy the XML into the new application's folder and run:

```sh
./start.sh --import DataFile-20261021T190000Z-12345678.xml
```

Absolute file paths are accepted too. Relative paths are resolved from the application folder when using `start.sh`. Import works with a fresh data directory or with the directory selected through `FREEMFT_DATA`. The command validates the file and proposed merged configuration, displays the number of new/matching records, and warns that overlapping data will be overwritten. **Type `YES` to apply the import and start the application.** Any other response, or end-of-input, cancels without starting the app or changing the stored configuration. An active instance using the same data directory blocks import. There is no unattended force/yes flag.

Import merges the configuration: matching accounts, profiles, destinations, and folder actions are replaced, while unrelated records remain. Administrator, SFTP listener, and ColdStorage settings are replaced by the export. Review shared profiles and global settings carefully because they may affect accounts already on the target. Invalid or conflicting configurations are rejected.

Changing an account's configured home does not move its existing files. Ensure required folders and scripts are available on the target. Missing scripts cause processing failures.

Before applying an import, FreeMFT saves the previous settings in `data/import-backups/BeforeImport-….xml`.

**Exports and automatic import backups contain sensitive credentials and are not encrypted.** Keep them private, restrict access, and transfer them only through a trusted channel. Do not publish them or attach them to public support requests.

Transferred files, script contents, queued jobs, and activity logs are **not** included in settings exports and are never replaced by import. Copy needed scripts and file storage separately. Configure environment settings such as `FREEMFT_ADMIN_HOST`, `FREEMFT_ADMIN_PORT`, and `FREEMFT_DATA` on the target separately. To restore previous settings, stop the app and import its BeforeImport backup with the same confirmation procedure. This is a settings merge, not a full rollback: records added by the first import remain unless removed separately.

To upgrade from 0.1.4 without importing, stop the old app, back up its data directory, extract 0.1.5 separately, and start it with `FREEMFT_DATA` pointing at the existing data directory. Normal startup behavior and stored credentials are preserved.

## System requirements

The application runtime is included. No separate runtime, database, or SSH server installation is required. Supported hosts need a standard **glibc Linux environment (glibc 2.28+, kernel 4.18+)**, such as Ubuntu 22.04/24.04 or Debian 12. Alpine/musl and 32-bit x86 are not supported. `tar` and a POSIX shell are used for extraction/startup.

Run under a dedicated non-root OS account with read/write access to the configured home folders and ColdStorage. Custom scripts run under that same account. Ports below 1024 require host privileges; use the default SFTP port **2222** for the pilot. Ctrl+C stops the application; SIGTERM is supported.

## Configure a first flow

1. In **Accounts**, add a password-authenticated account and an absolute home folder, for example `/usr/local/account32`. Choose **Default**, **onlyUpload**, **onlyDownload**, or a custom profile configured in **Permission profiles**. Home folders must not overlap each other, the application folder, or ColdStorage.
2. In **Services & storage**, set a ColdStorage root if needed, for example `/mnt/storage`.
3. For forwarding, add a **Destination** with the remote host, port, password, existing remote folder, and verified SSH host-key SHA-256 fingerprint. Obtain the fingerprint from the destination administrator in the required format: 64 hexadecimal characters. **Accept any SSH host key returned by this server** disables server identity verification. Leave it off unless explicitly testing that behavior in a controlled environment.
4. For scripts, put an executable file with a shebang into the application's `scripts/` folder. Example:

   ```sh
   # scripts/received.sh
   #!/bin/sh
   printf 'Received %s at %s from %s\n' "$1" "$2" "$3"
   ```

   Make it executable with `chmod 700 scripts/received.sh`. Host tools/interpreters required by a custom script must be installed separately. The application itself needs no additional installation.
5. In **Folder actions**, choose the account, a folder relative to its home (`/outbound` or `/process`), and one action: store, forward, or script. FreeMFT creates the folder. Choose keep, delete, or ColdStorage after success. Each folder has one rule; the most specific parent rule also applies to its subfolders. Unmatched folders store files without further action.
6. Under **Services & storage**, set the SFTP port and start the service. Its enabled state persists after restart. Stop it before changing ports; stopping disconnects active clients.
7. Connect using `sftp -P 2222 account32@SERVER`. Upload directly to a configured folder and inspect **Overview**, **Track Transfers**, **Job queue**, and **Activity log**.

The HTTPS **file transfer** interface is visibly disabled. The administrator console uses HTTP on port 8888; it is separate from that future interface. Restrict this pilot console to a trusted network or place it behind an HTTPS reverse proxy. Set `FREEMFT_ADMIN_HOST=127.0.0.1` to bind locally, or `FREEMFT_ADMIN_PORT` to override 8888. When proxying, preserve the external Host header. Sessions expire after eight hours and credential changes invalidate all sessions.

## Files, jobs, and recovery

- Successfully completed uploads trigger folder processing. Interrupted uploads are retained for inspection and are not processed automatically. Resuming partial uploads is not supported.
- **Overwrite** requires **Upload** permission. When enabled, normal uploads can replace existing files after successful completion. With Overwrite disabled, repeated ordinary uploads receive a unique filename suffix. Clients requesting exclusive creation fail if the name exists. Files in active transfers or unfinished processing jobs remain protected from replacement.
- Use direct final-filename uploads. Client modes that upload to a temporary name and then rename are **not supported in this pilot**: processing starts after the upload completes. Disable temporary filename/atomic rename mode and permission preservation in the client. Timestamp preservation requires explicit profile permission; setting timestamps through the open upload handle is supported. File/folder operations follow the assigned permission profile; action folders and files in use remain protected. Symlinks, hardlinks, filesystem permission/ownership changes, file resizing, and extended POSIX rename operations remain disabled.
- Shell access, remote commands, SSH tunneling, and legacy SCP are unavailable. Modern SCP clients in SFTP mode can transfer files when they use supported operations; SFTP clients are the primary supported interface.
- Pending jobs survive restarts. Folder-rule and destination changes affect new uploads; profile changes affect subsequent SFTP operations immediately. Account password changes apply to future sign-ins. Do not modify files externally while a job is waiting or running.
- Scripts receive the filename, absolute file path, and uploading username as their first three arguments. These values are also available as `FREEMFT_FILENAME`, `FREEMFT_PATH`, and `FREEMFT_USER`; `FREEMFT_JOB_ID` identifies the job. Exit code 0 means success; failures or timeouts retain the source. Script output and exit status appear in the activity history. Avoid printing secrets.
- Automatic retries default to **0** and can be set from 0–10. Manual retries are available. Make scripts safe to retry, using the job ID to recognize repeated work where appropriate. Jobs interrupted during processing become **needs-review**; check for external effects before retrying. Retention failures retry retention without rerunning the completed action.
- Forwarding uses the destination's configured host-key policy and creates the remote filename exclusively. An existing remote file fails rather than overwrites. A failed connection can leave a partial file on the remote; check/remove it there before manually retrying. The source is preserved on failure.
- ColdStorage mirrors the full absolute source path: `/usr/local/account32/report.csv` becomes `/mnt/storage/usr/local/account32/report.csv`. Existing archive names get a unique suffix. Ensure sufficient disk space. Inspect incomplete copies after an interruption before retrying.
- **Track Transfers** shows upload, download, and forwarding attempts with their endpoints, filenames, timestamps, status, and errors. **Activity log** provides the detailed event history, including authentication attempts, denied operations, script results, and configuration changes.
- Use filters and **Load older transfers** to find earlier activity. History has no automatic retention limit in this pilot. Monitor available storage and keep exported logs private.

## Persistence and backup

Keep the full `data/` directory private. It contains configuration, credentials, queued jobs, transfer history, and the SFTP host identity. Access to the complete directory may expose sensitive configuration and destination credentials.

Back up the full data directory **while the application is stopped**, as well as account homes, scripts, and ColdStorage. Restore them together. `FREEMFT_DATA` selects a different persistent data directory. Extract upgrades separately and reuse the existing data path; preserve the existing SFTP host identity. Only one FreeMFT process may use a data directory at a time.

This pilot intentionally excludes FTPS, AS2, workflow builders, complex routing, file transformations, clustering, and high availability. It has no quotas, malware scanning, or built-in administrator TLS certificate management.

## Additional permission behavior

- Profiles apply to the account's entire home directory; per-folder permission overrides are not supported. Folder actions configure processing, not access rights.
- Moving a file into an action folder does not trigger its action. Only successfully completed uploads enqueue processing.
- Move permits cross-folder moves of files and folders within the account home; Rename permits name changes within the same folder. Neither permits replacing an existing destination.
- Overwrite also requires Upload permission. A replacement takes effect only after the upload completes successfully and triggers the configured folder action. Exclusive-create uploads reject existing filenames. With Overwrite disabled, ordinary duplicate uploads receive a unique filename suffix. Files in active transfers or unfinished jobs remain protected.
- Set/preserve timestamps permits only access and modification times, through path or open-file requests. It does not allow chmod, ownership changes, or resizing. Upload handles can preserve timestamps before completion; protected processing files cannot be changed afterward until processing completes. Clients that set timestamps after upload completion may need to retry once processing finishes.
- Disabling directory listing creates a blind upload/download area: clients need known paths and some graphical clients may require listing permission to operate normally. Action folders remain protected regardless of profile permissions.

## Contact

For questions or feedback, contact **PM@FreeMFT.com**. Do not email passwords, configuration exports, private keys, or unredacted logs.