Administration Tools

Stylus SFTP Server provides three administration interfaces with 100% feature parity: a command-line interface (CLI), a Swing desktop GUI, and a web-based console. All three share the same AdminEngine backend and support identical operations. Choose whichever interface fits your workflow — every action available in one tool is available in the other two.

1. Command-Line Interface (CLI)

The CLI is a scriptable, non-interactive tool for managing the SFTP server from a terminal or from automation scripts. It connects directly to the database — the SFTP server does not need to be running for most commands.

Location

Usage

admin <command> [arguments]

Full Command Reference

The admin tool dispatches on the first positional argument. See Appendix A — CLI Command Reference for the complete list, grouped by category. This chapter summarises the categories only; the appendix carries the exact syntax and description of every command.

Database

User Management

Disk Quotas

SSH Public Keys

Audit & Sessions

Server Control

Configuration

Email Addresses

Credentials

LDAP Groups

Portal Configuration

Certificates

Multi-Factor Authentication

Help

Authentication

All three administration interfaces require authentication before granting access. Admin accounts are stored in the sftp_admin_users database table, which is separate from the SFTP user accounts in sftp_users. This provides an independent authentication boundary for administrative access.

Admin accounts are created during installation or via the CLI:

admin create-admin-user <username> --password <password>

Passwords are stored as BCrypt hashes. Admin accounts have an enabled flag that can be toggled independently.

2. Swing GUI (Desktop)

The desktop GUI provides a graphical interface for all administration tasks. Launch it with bin/admin-gui.bat on Windows.

Login

On launch, the Swing GUI displays a login dialog that requires admin credentials (username and password from the sftp_admin_users table). The dialog is modal — the main application window is not accessible until authentication succeeds. Closing the login dialog without authenticating exits the application.

Tabs

3. Web Console

The web-based administration console runs on an embedded Tomcat instance and provides the same capabilities as the CLI and Swing GUI through a browser interface.

Access

Features

• Ext JS frontend with the Triton theme for a modern, responsive interface.
• Dashboard with server status, active sessions, recent audit events, and disk usage overview. When a newer product version is published, a dismissible "New version available" card lists the changes since your version with a download link (see Update Notifications).
• REST API covering user management, audit, sessions, listener & security config, certificates, MFA, license administration, the full identity model (organizations, groups, virtual folders, folder permissions, auth providers), signing, and Portal branding — see Appendix D for the complete list (see Appendix for the full endpoint reference).
• Full parity: user CRUD, audit viewer, session management, certificate management, and all configuration operations.

AI Integration

The AI Integration tab controls whether AI assistants (Claude, GitHub Copilot, Open WebUI, and other Model Context Protocol clients) may connect to the Knowledge Base and read or author its content on a user's behalf. The feature is disabled by default; nothing is exposed until an administrator turns it on.

• Master switch — a single toggle enables or disables the MCP endpoint for the whole server. While off, the endpoint returns 503 Service Unavailable and no token, however valid, can reach it.
• Downloadable client configuration files — instead of hand-typing connection details, the tab generates a ready-to-use config file for each supported client:
  • mcp.json for Claude Code / Claude Desktop (and other mcpServers-style clients);
  • .vscode/mcp.json for Visual Studio Code with GitHub Copilot;
  • an Open WebUI tool-server import file.
  The generated files deliberately carry no token — the client obtains its own credential through browser sign-in (OAuth) on first use, so the file is safe to share within a team.
• Token management — the tab lists every active credential (both personal access tokens and OAuth-issued tokens, distinguished by kind) and lets an administrator revoke any of them. See Knowledge Base → Connecting AI Assistants for how tokens are issued, scoped, and authenticated.

The same settings are available from the CLI via admin get-ai-integration and admin set-ai-integration, and from the Swing desktop console's AI Integration panel.

4. License Management

The activation key that governs edition, licensed customer, expiry, and connection cap can be viewed, replaced, and cleared from every admin surface. All routes read and write the same activation.key file in the data directory, so the CLI, Swing GUI, and web console stay in lockstep.

A server restart is required for a new license to fully take effect. The maximum-connection cap is re-read on the server's hourly renewal timer, but listener gating (FTP/FTPS), LDAP provider selection, external audit sinks, and the storage-backend refusal are boot-time decisions. Every mutation surface prints a clear “restart the server to apply” message so operators know a restart is needed.

Where it lives

Updating the license

The Update dialog accepts the license payload in two formats, which are auto-detected on submission:

• Plain-text — the contents of an activation.key file, header + key=value lines including the signature=… line.
• Base64 / URL-encoded blob — a single-line encoding of the plain-text form. Both URL-safe and standard base64 alphabets are accepted, with or without padding. MIME line wrapping (76-column) is also tolerated.

After successful validation the file is written atomically. The parser enforces the same rules as boot-time load: signature must verify against the vendor public key, expiry must be in the future, product-version must match. Any failure surfaces as an inline error and nothing is written to disk.

Old-key archival

On every replace and every clear, the existing key is archived under the data directory before removal:

${STYLUS_SFTPSERVER_DATA}/backup_activation_keys/{iso-mtime}-activation.key

The filename encodes the archived file's modification time (colons replaced with dashes for cross-platform safety) so operators can identify when each historical key was originally installed. If two archives would collide on the same mtime, a numeric suffix is appended (-activation.1.key, -activation.2.key, …). The admin surface never deletes archived files — they are a filesystem safety net for manual rollback. To restore a previous key, copy the archive back to activation.key and restart the server.

Clearing the license (downgrade to Free)

The Clear action removes activation.key after archiving it. On next restart the server falls back to Free Edition via the built-in free-fallback logic. Enterprise features (FTP/FTPS listener, external audit sinks, LDAP, MFA, quotas, GeoIP, Portal Sign) stop being available once the restart completes. The Clear dialog and the CLI's license-clear --confirm flag both surface this consequence explicitly before proceeding.

Audit trail

Every mutation writes an audit event:

• LICENSE_UPDATE — detail carries old=<edition> new=<edition> customer=<id> expires=<iso>.
• LICENSE_CLEAR — detail carries old=<edition>.

The acting admin operator is stamped via the standard executed-by mechanism, so audit rows carry both the change and who made it.

Server Commands via Database

The admin tools do not communicate with the SFTP server over a network socket. Instead, they write command records to the sftp_commands database table. The server's CommandPoller polls this table every 2 seconds and executes pending commands.

This design means the admin tools can run on a completely different machine from the server, as long as both can reach the same database.

Supported Commands

Server Heartbeat

The ServerHeartbeat component updates the sftp_server_status table every 10 seconds, allowing admin tools to display up-to-date server information without a direct connection to the server process.

Tracked Fields