Virtual File System

CompleteFTP's virtual file system is one of its most powerful features, allowing you to create a unified file structure that can map to various storage backends including local directories, network shares, cloud storage, and remote servers. This flexibility enables complex file organization scenarios while presenting a simple, consistent interface to users.

Overview

The virtual file system provides:

• Flexible mapping - Map virtual folders to different storage types
• Unified namespace - Present disparate storage as a single file tree
• Access control - Fine-grained permissions on folders and files
• Storage abstraction - Hide underlying storage complexity from users
• Scalability - Add storage without changing user experience

All folder operations use the completeftp folder command group.

Understanding the Virtual File System

Virtual vs. Physical Structure

CompleteFTP separates the logical file structure (what users see) from the physical storage (where files are actually stored):

• Virtual paths - The folder structure users navigate (e.g., /Home/alice, /Projects/Alpha)
• Physical mappings - Where the data actually resides (e.g., /var/ftp/users/alice, s3://mybucket/projects/alpha)
• Folder types - Different storage backends (OS, Amazon S3, Azure, Gateway, etc.)
• Access control - Permissions applied to virtual paths regardless of underlying storage

Folder Types

CompleteFTP supports several folder types:

Type	Description	Use Cases
OS	Local file system directories	Local storage, network shares
AmazonS3	Amazon S3 buckets and paths	Cloud storage, scalable storage
Azure	Azure Blob Storage containers	Microsoft cloud integration
Gateway	Remote FTP/FTPS/SFTP servers	Federated access, legacy systems
Virtual	Logical folders with no storage	Organization, navigation structure

Cloud & Advanced Storage Available: CompleteFTP can integrate with Amazon S3, Azure Blob Storage, network shares, and remote FTP servers as seamlessly as local directories. Advanced features include encryption at rest, ZIP file mounting, and filename filtering. See Advanced Features Overview for details.

Viewing Folder Information

List Folders

# List root-level folders
completeftp folder list

# List subfolders of a specific path
completeftp folder list /Home

# List with detailed information
completeftp folder list /Projects --details

# List all folders in the system
completeftp folder listall

# List all folders with details
completeftp folder listall --details

Show Folder Details

# Show all properties of a folder
completeftp folder show /Home/alice

# Show specific properties
completeftp folder show /Home/alice type mappingPath access

# Use interactive viewer for detailed exploration
completeftp folder show /Home/alice -v

# Show multiple folders
completeftp folder show /Home/alice /Projects/Alpha /Shared

Creating and Managing Folders

Adding Folders

OS Folders (Local File System)

# Add a simple OS folder
completeftp folder add /Home/bob OS path=/var/ftp/users/bob

# Add folder with mapping shorthand
completeftp folder add /Home/charlie OS --mapping=/var/ftp/users/charlie

# Add network share folder
completeftp folder add /Shared/Network OS path=//server/share

# Add folder with credentials for network access
completeftp folder add /Shared/Secure OS \
  path=//server/secure credentials.userName=ftpuser credentials.password=ftppass

Cloud Storage Folders

# Add Amazon S3 folder
completeftp folder add /Cloud/S3Data AmazonS3 \
   bucket=my-ftp-bucket path=data

# Add S3 folder with credentials
completeftp folder add /Cloud/S3Private AmazonS3 \
   bucket=private-bucket path=users accessKey=AKIAIOSFODNN7EXAMPLE secretKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Add Azure Blob Storage folder
completeftp folder add /Cloud/Azure Azure \
  containerName=ftpdata path=uploads

# Add Azure folder with connection string
completeftp folder add /Cloud/AzureSecure Azure \
  containerName=secure connectionString=DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey

Gateway Folders (Remote Servers)

# Add SFTP gateway folder
completeftp folder add /Remote/SFTP Gateway --mapping sftp://remoteuser:remotepass@remote.example.com/data

# Add FTP gateway folder
completeftp folder add /Remote/FTPS Gateway --mapping ftp://legacyuser:legacypass@legacy.example.com/files

# Add gateway folder with SSH key authentication
completeftp folder add /Remote/SSHKey Gateway --mapping sftp://remoteuser:remotepass@remote.example.com/data
completeftp folder set /Remote/SSHKey mapping.specifiedConnection.clientPrivateKey=/path/to/key

Virtual Folders

# Add virtual folder for organization
completeftp folder add /Departments Virtual

# Add nested virtual folders
completeftp folder add /Departments/Engineering Virtual
completeftp folder add /Departments/Marketing Virtual
completeftp folder add /Departments/Sales Virtual

Modifying Folder Properties

# Change folder mapping
completeftp folder set /Home/alice mapping.path=/new/path/alice

# Update folder credentials
completeftp folder set /Shared/Network \
  "mapping.credentials.userName=newuser" \
  "mapping.credentials.password=newpass"

# Hide folder from listings
completeftp folder set /Admin hidden=true

# Enable recursive listing
completeftp folder set /Projects showRecursiveListing=true

Moving and Renaming Folders

# Move folder to new parent
completeftp folder move /OldLocation/MyFolder /NewParent

# Renaming a folder
completeftp folder move /Home/temp_user /Home/joe

Removing Folders

# Remove a folder (non-recursive by default)
completeftp folder remove /Temp/OldProject

# Remove folder and all subfolders
completeftp folder remove /Temp/CompleteProject --recursive=true

Warning: Removing folders only removes them from the virtual file system. The underlying data storage is not affected.

Folder Permissions and Access Control

Setting Folder Ownership

# Set user as folder owner
completeftp folder chown /Home/alice owner alice

# Set group as folder owner
completeftp folder chown /Projects/Alpha group developers

# Set both user and group ownership
completeftp folder chown /Shared/Marketing owner marketing_lead
completeftp folder chown /Shared/Marketing group marketing

Setting Folder Permissions

# Set owner permissions
completeftp folder chmod /Home/alice owner rwxd

# Set group permissions
completeftp folder chmod /Projects/Alpha group rw

# Set permissions for all users
completeftp folder chmod /Public all r

# Set multiple permission types
completeftp folder chmod /Shared/Uploads owner rwxd
completeftp folder chmod /Shared/Uploads group rw
completeftp folder chmod /Shared/Uploads all w

Permission Types

Available permission flags:

• r - Read (list files, download)
• w - Write (upload, modify files)
• x - Execute (access directories)
• d - Manage directories (create/delete folders)
• i - Ignore filters (bypass file name filters)

Common Permission Scenarios

# Full access for owner, read-only for group
completeftp folder chmod /Home/alice owner rwxd
completeftp folder chmod /Home/alice group r

# Collaborative project folder
completeftp folder chmod /Projects/Shared owner rwxd
completeftp folder chmod /Projects/Shared group rwxd

# Upload-only folder
completeftp folder chmod /Uploads all w

# Public read-only folder
completeftp folder chmod /Public all r

# Admin-only folder
completeftp folder chmod /Admin owner rwxdi
completeftp folder chmod /Admin group ""
completeftp folder chmod /Admin all ""

Virtual File System Workflows

User Home Directory Setup

# 1. Create home directory structure
completeftp folder add /Home Virtual

# 2. Add individual user folders
completeftp folder add /Home/alice OS --mapping="/var/ftp/users/alice"
completeftp folder add /Home/bob OS --mapping="/var/ftp/users/bob"
completeftp folder add /Home/charlie3 AmazonS3 bucket=user-storage directory=charlie

# 3. Set appropriate permissions
completeftp folder chown /Home/alice owner alice
completeftp folder chmod /Home/alice owner rwxd

completeftp folder chown /Home/bob owner bob
completeftp folder chmod /Home/bob owner rwxd

completeftp folder chown /Home/charlie owner charlie
completeftp folder chmod /Home/charlie owner rwxd

# 4. Set users' home directories
completeftp user home alice /Home/alice
completeftp user home bob /Home/bob
completeftp user home charlie /Home/charlie

Department-Based Structure

# 1. Create department structure
completeftp folder add /Departments Virtual
completeftp folder add /Departments/Engineering OS --mapping=/var/ftp/engineering
completeftp folder add /Departments/Marketing OS --mapping=/var/ftp/marketing
completeftp folder add /Departments/Sales AmazonS3 \
  bucket=company-data directory=sales

# 2. Create project subfolders
completeftp folder add /Departments/Engineering/Projects Virtual
completeftp folder add /Departments/Engineering/Projects/Alpha OS \
  --mapping=/var/ftp/engineering/projects/alpha
completeftp folder add /Departments/Engineering/Projects/Beta OS \
  --mapping=/var/ftp/engineering/projects/beta

# 3. Set department permissions
completeftp folder chown /Departments/Engineering group engineering
completeftp folder chmod /Departments/Engineering group rwxd

completeftp folder chown /Departments/Marketing group marketing
completeftp folder chmod /Departments/Marketing group rwxd

completeftp folder chown /Departments/Sales group sales
completeftp folder chmod /Departments/Sales group rwxd

# 4. Set project permissions
completeftp folder chown /Departments/Engineering/Projects/Alpha group project_alpha
completeftp folder chmod /Departments/Engineering/Projects/Alpha group rwxd

Hybrid Cloud Storage

# 1. Create cloud storage structure
completeftp folder add /Cloud Virtual
completeftp folder add /Cloud/Archive AmazonS3 \
   bucket=company-archive directory=files
completeftp folder add /Cloud/Backup Azure \
  containerName=backups directory=daily

# 2. Create local hot storage
completeftp folder add /Hot OS --mapping="/var/ftp/hot"

# 3. Create shared access points
completeftp folder add /Shared Virtual
completeftp folder add /Shared/Current OS --mapping="/var/ftp/current"
completeftp folder add /Shared/Archive AmazonS3 \
   bucket=company-archive directory=shared

# 4. Set tiered permissions
completeftp folder chmod /Hot all rw
completeftp folder chmod /Shared/Current all rw
completeftp folder chmod /Shared/Archive all r
completeftp folder chmod /Cloud/Archive group admins

Gateway Integration

# 1. Create remote access structure
completeftp folder add /Remote Virtual
completeftp folder add /Remote/Legacy Gateway \
  --mapping="ftp://ftpuser:ftppass@legacy.company.com/data"

# 2. Add secure remote access
completeftp folder add /Remote/Partner Gateway \
  --mapping="sftp://partneruser@partner.example.com/data"

# 3. Create federated structure  
completeftp folder add /Federated Virtual
completeftp folder add /Federated/Site1 Gateway \
  --mapping="ftps://siteuser:sitepass@site1.company.com/files"
completeftp folder add /Federated/Site2 Gateway \
  --mapping="sftp://siteuser@site2.company.com/data"

# 4. Set access controls
completeftp folder chmod /Remote/Legacy group legacy_users
completeftp folder chmod /Remote/Partner group partner_access
completeftp folder chmod /Federated group site_admins

Advanced Folder Management

Folder Macros

CompleteFTP supports macros in folder names and mappings:

# User-specific folders with macros
completeftp folder add "/Home/%UserName%" OS \
  --mapping="/var/ftp/users/%UserName%"

# Date-based folders
completeftp folder add "/Logs/%Year%/%Month%" OS \
  --mapping="/var/log/ftp/%Year%/%Month%"

# Site-specific folders
completeftp folder add "/Sites/%SiteName%/uploads" OS \
  --mapping="/var/ftp/sites/%SiteName%/uploads"

Available macros include:

• %UserName% - Current user's username
• %SiteName% - Current site name
• %Year% - Current year (4 digits)
• %Month% - Current month (2 digits)
• %Day% - Current day (2 digits)
• %Hour% - Current hour (2 digits)

Conditional Folder Access

# Create folders with conditional access
completeftp folder add /Secure OS --mapping="/var/ftp/secure"
completeftp folder chmod /Secure owner rwxd
completeftp folder chmod /Secure group ""
completeftp folder chmod /Secure all ""

# Create time-based access folders
completeftp folder add /Business-Hours OS --mapping="/var/ftp/business"
# Note: Time-based access would be configured through extensions or triggers

Folder Monitoring and Auditing

# View folder access information
completeftp folder show /Sensitive access

# Check if folder has subfolders
completeftp folder show /Projects hasSubfolders

# List all folders for audit
completeftp folder listall | grep -E "(type|access|mapping)"

Troubleshooting Virtual File System Issues

Common Folder Problems

Folder Not Accessible

# Check if folder exists
completeftp folder show /path/to/folder

# Verify folder permissions
completeftp folder show /path/to/folder access

# Check folder mapping
completeftp folder show /path/to/folder mapping

# Verify underlying storage is accessible
# (This depends on the folder type and mapping)

Mapping Issues

# Check folder type and mapping
completeftp folder show /problematic/folder type mapping.path

# Verify credentials for network/cloud folders
completeftp folder show /problematic/folder mapping.credentials.userName mapping.credentials.password

# Test underlying path accessibility
ls -la /var/ftp/path  # For OS folders

Permission Problems

# Check folder ownership
completeftp folder show /folder access.owner access.group

# Verify user/group permissions
completeftp folder show /folder access.owner.permissions access.group.permissions

# Check if user is in required group
completeftp group memberlist groupname | grep username

# Verify user has required protocol access
completeftp user show username sftpEnabled ftpEnabled

Performance Issues

# Check for recursive listing settings
completeftp folder show /slow/folder showRecursiveListing

# Verify cloud storage credentials and connectivity
# (Test outside CompleteFTP if possible)

# Check gateway folder connectivity
# (Test remote server access independently)

# Review folder structure complexity
completeftp folder listall | wc -l

Best Practices

Folder Design

1. Logical hierarchy - Create intuitive folder structures that match user expectations
2. Consistent naming - Use clear, consistent naming conventions
3. Appropriate depth - Avoid overly deep folder hierarchies
4. Purpose-driven organization - Group folders by function, department, or project
5. Scalability planning - Design structures that can grow with your organization

Storage Strategy

1. Match storage to usage - Use appropriate storage types for different use cases
2. Performance considerations - Place frequently accessed data on fast storage
3. Cost optimization - Use cloud storage for archival and backup data
4. Redundancy planning - Consider backup and disaster recovery needs
5. Access patterns - Optimize folder structure for common access patterns

Security and Access Control

1. Principle of least privilege - Grant minimum necessary permissions
2. Regular audits - Review folder permissions and access patterns
3. Sensitive data protection - Use appropriate security for confidential folders
4. Access logging - Monitor folder access for security and compliance
5. Credential management - Secure storage of cloud and network credentials

Maintenance and Operations

1. Documentation - Document folder purposes and access requirements
2. Change management - Track folder structure changes
3. Monitoring - Watch for folder access issues and performance problems
4. Cleanup procedures - Regular removal of unused folders and data
5. Backup verification - Ensure folder mappings are included in backups

Quick Reference

Folder Management Commands

# List folders
completeftp folder list [path] [--details]
completeftp folder listall [--details]

# Show folder details
completeftp folder show <path> [properties]

# Add folder
completeftp folder add <path> <type> [--mapping=<mapping>]

# Modify folder
completeftp folder set <path> property=value

# Move folder
completeftp folder move <folder> <parentFolder>

# Remove folder
completeftp folder remove <path> [--recursive]

Permission Commands

# Set ownership
completeftp folder chown <path> owner <userName>
completeftp folder chown <path> group <groupName>

# Set permissions
completeftp folder chmod <path> owner <permissions>
completeftp folder chmod <path> group <permissions>
completeftp folder chmod <path> all <permissions>

Folder Types and Mappings

# OS folder
OS --mapping=/local/path

# Amazon S3 folder
AmazonS3  bucket=bucket directory=prefix

# Azure folder
Azure containerName=container directory=prefix

# Gateway folder
Gateway --mapping="sftp://user:pass@host/path"

# Virtual folder
Virtual

Permission Flags

r = read (list files, download)
w = write (upload, modify files)
x = execute (access directories)
d = manage directories (create/delete folders)
i = ignore filters (bypass file name filters)

Common Macros

%UserName% = Current user's username
%SiteName% = Current site name
%Year% = Current year (YYYY)
%Month% = Current month (MM)
%Day% = Current day (DD)