thuFileZillaAPI v2

User and group management tool for FileZilla Server 1.x via the admin protocol.

All changes are pushed directly through the FileZilla Server admin interface (TCP 14148) — no XML files are modified, no service restart needed. Changes take effect immediately.

Compatibility

• FileZilla Server 1.9.x through 1.12.6 (protocol versions 47–70)
• .NET Framework 4.7.2
• Windows Server 2016 or later

Requirements

• FileZilla Server must be running with the administration interface enabled (default: TCP 14148)
• The admin password must be known (set during FileZilla Server installation)
• For REST API server mode: the configured HTTP port (default 14150) must be available

Configuration

Settings are read from App.config (or thuFileZillaAPI-v2.exe.config):

Key	Default	Description
AdminHost	127.0.0.1	FileZilla Server admin host
AdminPort	14148	FileZilla Server admin port
AdminPassword	(empty)	Admin password (can also use /adminpassword:)
ListenAddress	127.0.0.1	REST API listen address (server mode)
ListenPort	14150	REST API listen port (server mode)
ConfigPath	C:\ProgramData\filezilla-server	Path to FileZilla Server config (for API key validation)

The admin password can always be overridden on the command line with /adminpassword:yourpassword.

---

Mode 1: Command Line (CLI)

Run one-off commands from cmd.exe, PowerShell, or scripts (batch files, scheduled tasks, etc.).

Add User

thuFileZillaAPI-v2.exe [/adminpassword:MyStrongPassword] /action:adduser
  /username:john /password:secret123 [options]

Delete User

thuFileZillaAPI-v2.exe [/adminpassword:MyStrongPassword] /action:deluser /username:john

Change Password

thuFileZillaAPI-v2.exe [/adminpassword:MyStrongPassword] /action:pwduser
  /username:john /password:newpass

Add Group

thuFileZillaAPI-v2.exe [/adminpassword:MyStrongPassword] /action:addgroup
  /groupname:WebUsers [options]

Delete Group

thuFileZillaAPI-v2.exe [/adminpassword:MyStrongPassword] /action:delgroup /groupname:WebUsers

Note: A group cannot be deleted if users are still assigned to it.

Shared Parameters for Add User / Add Group

The following parameters apply to both /action:adduser and /action:addgroup:

Parameter	Required	Default	Description
/adminpassword:	Yes*	—	FileZilla Server admin password (*unless set in App.config)
/username:	adduser only	—	FTP username
/password:	adduser only	—	FTP password
/groupname:	addgroup: required, adduser: optional	—	Group name (adduser: assigns user to group)
/directory:	No	—	Native filesystem path for mount point (e.g. "D:\FTP\user")
/aliases:	No	"/"	Virtual path(s), pipe-separated (e.g. "/pub_html\|/public_html")
/acl:	No	ReadWrite	Access mode: ReadOnly, ReadWrite, WriteOnly, Disabled
/recursive:	No	Full	Subdirectory permissions: None, Apply, Full
/autocreate:	No	no	Create native directory if missing: yes / no
/comment:	No	—	Description text
/allowed_ips:	No	—	Allowed IPs (semicolon-separated, see Filters)
/disallowed_ips:	No	—	Disallowed IPs (semicolon-separated, see Filters)
/download_limit:	No	unlimited	Shared download speed in KiB/s
/upload_limit:	No	unlimited	Shared upload speed in KiB/s
/session_download_limit:	No	unlimited	Per-session download speed in KiB/s
/session_upload_limit:	No	unlimited	Per-session upload speed in KiB/s
/max_files:	No	unlimited	Max open files per session
/max_dirs:	No	unlimited	Max open directories per session
/max_sessions:	No	unlimited	Max concurrent sessions
/ftp_policy:	No	default	FTP (insecure) policy: default, enabled, disabled
/ftps_policy:	No	default	FTPS (TLS) policy: default, enabled, disabled

CLI Examples

Add user with group and mount point:

thuFileZillaAPI-v2.exe /adminpassword:MyStrongPassword /action:adduser /username:webuser /password:Str0ngPwd! /groupname:WebUsers /directory:"D:\InetPub\FTP-Root" /aliases:"/pub_html" /acl:ReadWrite /recursive:Full /comment:"Web publishing account"

Add user with speed limits and IP filter:

thuFileZillaAPI-v2.exe /adminpassword:MyStrongPassword /action:adduser /username:limited /password:secret123 /groupname:FreeAbo /directory:"D:\FTP\limited" /aliases:"/" /download_limit:100 /upload_limit:50 /max_sessions:2 /allowed_ips:"192.168.0.0/16;10.0.0.0/8"

Add group with read-only access and FTPS required:

thuFileZillaAPI-v2.exe /adminpassword:MyStrongPassword /action:addgroup /groupname:FreeAbo /directory:"D:\InetPub\FTP-Root\free" /aliases:"/" /acl:ReadOnly /recursive:Apply /ftp_policy:disabled /ftps_policy:enabled /comment:"Free tier — FTPS only"

Add group with multiple virtual paths:

thuFileZillaAPI-v2.exe /adminpassword:MyStrongPassword /action:addgroup /groupname:WebDevs /directory:"D:\WebRoot" /aliases:"/pub_html|/public_html|/www"

---

Mode 2: REST API Server

Run as a persistent HTTP server for integration with web applications, scripts, or other systems.

Start the Server

thuFileZillaAPI-v2.exe [/adminpassword:MyStrongPassword] /server

The server listens on http://127.0.0.1:14150/ by default (configurable via App.config).

Press Ctrl+C or Q to stop.

Install as Windows Service

sc create thuFileZillaAPI binPath= "C:\path\to\thuFileZillaAPI-v2.exe /adminpassword:MyStrongPassword /server"
sc start thuFileZillaAPI

Authentication

All API endpoints (except /api/status) require the X-Api-Key header:

X-Api-Key: MyStrongPassword

Endpoints

GET /api/status — Health Check (no auth required)

curl http://127.0.0.1:14150/api/status

POST /api/user — Add User

curl -X POST http://127.0.0.1:14150/api/user \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: MyStrongPassword" \
  -d '{
    "username": "john",
    "password": "secret123",
    "group": "WebUsers",
    "directory": "D:\\FTP\\john",
    "aliases": ["/"],
    "acl": "ReadWrite",
    "recursive": "Full",
    "description": "John Doe",
    "download_limit": "100",
    "upload_limit": "50",
    "max_sessions": "3",
    "ftp_policy": "disabled",
    "ftps_policy": "enabled"
  }'

DELETE /api/user?username=john — Delete User

curl -X DELETE "http://127.0.0.1:14150/api/user?username=john" \
  -H "X-Api-Key: MyStrongPassword"

PUT /api/user/password — Change Password

curl -X PUT http://127.0.0.1:14150/api/user/password \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: MyStrongPassword" \
  -d '{"username": "john", "password": "newpass123"}'

POST /api/group — Add Group

curl -X POST http://127.0.0.1:14150/api/group \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: MyStrongPassword" \
  -d '{
    "groupname": "Premium",
    "directory": "D:\\FTP\\premium",
    "aliases": ["/"],
    "acl": "ReadWrite",
    "recursive": "Full",
    "description": "Premium accounts",
    "allowed_ips": "192.168.0.0/16;10.0.0.0/8",
    "ftps_policy": "enabled"
  }'

DELETE /api/group?groupname=Premium — Delete Group

curl -X DELETE "http://127.0.0.1:14150/api/group?groupname=Premium" \
  -H "X-Api-Key: MyStrongPassword"

REST API Body Fields (Add User / Add Group)

All fields from the CLI are available in the JSON body with the same names. Additionally:

Field	Type	Description
username	string	FTP username (adduser only, required)
password	string	FTP password (adduser only, required)
group	string	Assign to group (adduser only)
groupname	string	Group name (addgroup only, required)
directory	string	Native filesystem path
aliases	string or array	Virtual paths — "/", "/a|/b", or ["/a", "/b"]
acl	string	ReadOnly, ReadWrite, WriteOnly, Disabled
recursive	string	None, Apply, Full
autocreate	string	yes / no
enabled	bool	Account enabled (adduser only, default: true)
description	string	Description text
allowed_ips	string	Semicolon-separated IP ranges
disallowed_ips	string	Semicolon-separated IP ranges
download_limit	string	KiB/s or "unlimited"
upload_limit	string	KiB/s or "unlimited"
session_download_limit	string	KiB/s or "unlimited"
session_upload_limit	string	KiB/s or "unlimited"
max_files	string	Number or "unlimited"
max_dirs	string	Number or "unlimited"
max_sessions	string	Number or "unlimited"
ftp_policy	string	default, enabled, disabled
ftps_policy	string	default, enabled, disabled

---

Mount Options

These match the settings in the FileZilla Server GUI exactly.

Access Mode (/acl)

Value	Aliases	Numeric	Description
ReadOnly	Read, RO	0	Download only
ReadWrite	RW, Full	1	Upload and download (default)
Disabled	None, Off	2	No access
WriteOnly	Write, WO	3	Upload only

Recursive Mode (/recursive)

Value	Aliases	Numeric	GUI Equivalent
None	Off, No	0	Both checkboxes unchecked
Apply	Yes, On	1	☑ Apply permissions to subdirectories
Full	Writable, Structure	2	☑ Apply permissions to subdirectories + ☑ Writable directory structure (default)

Autocreate (/autocreate)

Value	GUI Equivalent
yes	☑ Create native directory if it does not exist
no	Unchecked (default)

---

Filters (IP Ranges)

Restrict access by IP address. Accepts semicolon-separated entries (IPv4).

CLI: /allowed_ips:"192.168.1.0/24;10.0.0.1" /disallowed_ips:"172.16.0.0/12" REST API: "allowed_ips": "192.168.1.0/24;10.0.0.1"

Format	Example	Description
Single IP	192.168.1.1	Exact match
CIDR	192.168.1.0/24	Subnet (192.168.1.0 – 192.168.1.255)
Range	192.168.1.1-192.168.1.100	Explicit from–to range

Multiple entries: "10.0.0.0/8;192.168.0.0/16;172.16.5.1"

---

Speed & Session Limits

Parameter	GUI Equivalent	Unit	Default
download_limit	Speed limits shared — Download from server	KiB/s	unlimited
upload_limit	Speed limits shared — Upload to server	KiB/s	unlimited
session_download_limit	Speed limits per session — Download	KiB/s	unlimited
session_upload_limit	Speed limits per session — Upload	KiB/s	unlimited
max_files	Filesystem limits — Files	count	unlimited (0)
max_dirs	Filesystem limits — Directories	count	unlimited (0)
max_sessions	Concurrent sessions limit	count	unlimited (0)

Use unlimited or omit the parameter for no limit.

---

Protocol Policies

Override FTP/FTPS authentication policies per user or group.

Value	For Users	For Groups
default	Determined by groups or system policies	Determined by other groups or system policies
enabled	Enabled — overrides groups policies	Enabled
disabled	Disabled — overrides groups policies	Disabled

Typical setup: Disable insecure FTP, require FTPS:

/ftp_policy:disabled /ftps_policy:enabled

---

Error Messages

Error Message	Cause / Fix
Login failed: wrong admin password.	Check /adminpassword value.
User 'xxx' already exists.	Use /action:pwduser to change password, or delete first.
Group 'xxx' does not exist.	Create the group first with /action:addgroup.
Cannot delete group: still assigned to users	Remove users from the group first.
Could not find matching protocol version	FileZilla Server version not supported or admin interface unreachable.
AdminPassword is not configured.	Provide /adminpassword:xxx or set it in App.config.

Troubleshooting

1. Connection timeout / hangs: Verify FileZilla Server is running and admin interface is enabled on port 14148.
2. TLS errors: The tool uses BouncyCastle for TLS and accepts self-signed certificates (normal for admin interface).
3. REST API "401 Unauthorized": The X-Api-Key header must match the FileZilla Server admin password.
4. REST API listener fails to start: Run as Administrator, or grant URL reservation: netsh http add urlacl url=http://127.0.0.1:14150/ user=Everyone

Autor

thu@thu.ch