1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Basic PWD Usage
→ PWD
← 257 "/home/developer" is the current directory
 
# Unix-style path
→ PWD
← 257 "/var/www/html/uploads"
 
# Windows server (drive letter)
→ PWD
← 257 "C:/FTPRoot/Users/admin"
 
# Root directory
→ PWD
← 257 "/" is current directory
 
# Path with spaces (quotes are essential)
→ PWD
← 257 "/home/user/My Documents/Projects" is current directory
 
# Chroot-jailed user (sees / but actually in /home/user/ftp)
→ PWD
← 257 "/" is current directory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# Absolute path navigation
→ PWD
← 257 "/home/developer"
→ CWD /var/www/html
← 250 Directory successfully changed
→ PWD
← 257 "/var/www/html"
 
# Relative path navigation
→ PWD
← 257 "/var/www"
→ CWD html/images
← 250 CWD command successful
→ PWD
← 257 "/var/www/html/images"
 
# Parent directory with ..
→ PWD
← 257 "/var/www/html/images"
→ CWD ..
← 250 Directory changed to /var/www/html
→ PWD
← 257 "/var/www/html"
 
# Navigate to root
→ CWD /
← 250 CWD command successful
 
# Path with spaces (must handle correctly)
→ CWD /home/user/My Documents
← 250 Directory successfully changed
 
# Error: Directory doesn't exist
→ CWD /nonexistent/path
← 550 /nonexistent/path: No such file or directory
 
# Error: Permission denied
→ CWD /root
← 550 Failed to change directory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# Standard parent directory navigation
→ PWD
← 257 "/var/www/html/images"
→ CDUP
← 250 CDUP command successful
→ PWD
← 257 "/var/www/html"
 
# Multiple CDUP commands
→ PWD
← 257 "/var/www/html/assets/css"
→ CDUP
← 250 Directory changed
→ CDUP
← 250 Directory changed
→ PWD
← 257 "/var/www/html"
 
# At root directory (chroot jail)
→ PWD
← 257 "/"
→ CDUP
← 250 Directory changed  # Often stays at /
→ PWD
← 257 "/"
 
# Some servers return 550 at root
→ PWD
← 257 "/"
→ CDUP
← 550 Cannot change to parent directory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# LIST Command - Detailed Output (Unix-style server)
→ LIST
← 150 Opening ASCII mode data connection for file list
# Data connection sends:
drwxr-xr-x    3 user     group        4096 Jan 15 10:30 documents
-rw-r--r--    1 user     group      123456 Jan 14 08:22 report.pdf
-rw-r--r--    1 user     group        8192 Jan 12 16:45 data.csv
lrwxrwxrwx    1 user     group          11 Jan 10 09:00 latest -> report.pdf
drwxr-xr-x    2 user     group        4096 Dec 28 14:30 archive
← 226 Transfer complete
 
# NLST Command - Simple Name List
→ NLST
← 150 Opening ASCII mode data connection for file list
# Data connection sends:
documents
report.pdf
data.csv
latest
archive
← 226 Transfer complete
 
# LIST with wildcards (server support varies)
→ LIST *.pdf
← 150 Opening connection
-rw-r--r--    1 user     group      123456 Jan 14 08:22 report.pdf
-rw-r--r--    1 user     group       56789 Jan 11 11:11 summary.pdf
← 226 Transfer complete
 
# LIST specific subdirectory
→ LIST /var/www/html
← 150 Opening connection
drwxr-xr-x    2 www-data www-data    4096 Jan 15 12:00 assets
-rw-r--r--    1 www-data www-data    1234 Jan 15 11:30 index.html
← 226 Transfer complete

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# Creating directories
 
# Simple directory creation
→ MKD newproject
← 257 "newproject" created
 
# Absolute path creation
→ MKD /var/www/html/uploads/2025
← 257 "/var/www/html/uploads/2025" directory created
 
# Nested path (typically fails - no recursive creation)
→ MKD deep/nested/path
← 550 deep: No such file or directory
# Must create each level:
→ MKD deep
← 257 "deep" created
→ MKD deep/nested
← 257 "deep/nested" created
→ MKD deep/nested/path
← 257 "deep/nested/path" created
 
# Directory name with spaces
→ MKD "Project Files"
← 257 "Project Files" created
 
# Directory already exists
→ MKD existing_dir
← 550 existing_dir: File exists
 
# ============================================
# Removing directories
 
# Simple removal
→ RMD oldproject
← 250 RMD command successful
 
# Absolute path removal
→ RMD /var/www/html/temp
← 250 Directory removed
 
# Directory not empty (fails)
→ RMD project_with_files
← 550 Directory not empty
 
# Directory doesn't exist
→ RMD nonexistent
← 550 No such file or directory
 
# Permission denied
→ RMD /protected
← 550 Permission denied

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

def ftp_mkdir_recursive(ftp_client, path: str) -> None:
    """
    Create directory path recursively on FTP server.
    Equivalent to mkdir -p behavior.
    """
    # Normalize path separators and split
    parts = path.replace('\\', '/').strip('/').split('/')
    
    current = ""
    for part in parts:
        current = current + "/" + part if current else "/" + part
        
        try:
            ftp_client.mkd(current)
            print(f"Created: {current}")
        except Exception as e:
            # 550 could mean "exists" or "permission denied"
            # Try to verify it exists
            try:
                ftp_client.cwd(current)
                print(f"Exists:  {current}")
            except:
                # Directory neither exists nor can be created
                raise RuntimeError(
                    f"Cannot create or access {current}: {e}"
                )
    
    # Return to original directory after verification
    ftp_client.cwd(path)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Example ProFTPD Virtual Directory Configuration
 
# Default directory for all users
DefaultRoot ~
 
# Virtual paths visible to all authenticated users
VirtualHost 0.0.0.0 {
    # /shared maps to /var/ftp/shared
    <Anonymous /var/ftp>
        <Limit LOGIN>
            DenyAll
        </Limit>
    </Anonymous>
}
 
# User-specific virtual directories
<Directory /home/*>
    <Limit ALL>
        AllowAll
    </Limit>
</Directory>
 
# Create virtual /public that all users can see
# Actually stored at /var/ftp/public
# User sees: /public
# Server accesses: /var/ftp/public

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# LIST showing symbolic links
→ LIST
← 150 Opening data connection
 
# Regular file
-rw-r--r--    1 user  group    12345 Jan 15 10:00 report.pdf
 
# Directory
drwxr-xr-x    2 user  group     4096 Jan 14 09:00 documents
 
# Symbolic link to file
lrwxrwxrwx    1 user  group       10 Jan 13 08:00 latest.pdf -> report.pdf
 
# Symbolic link to directory
lrwxrwxrwx    1 user  group       12 Jan 12 07:00 docs -> documents
 
# Broken symbolic link (target doesn't exist)
lrwxrwxrwx    1 user  group       15 Jan 11 06:00 broken -> nonexistent
 
# Absolute symlink (potentially problematic)
lrwxrwxrwx    1 user  group       14 Jan 10 05:00 systemlog -> /var/log/system.log
 
← 226 Transfer complete

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# ProFTPD Symlink Security Configuration
 
# Only show symlinks that point within user's home
ShowSymlinks on
AllowSymlinks inside
 
# Prevent following symlinks entirely (most restrictive)
# ShowSymlinks off
 
# vsftpd equivalent configuration
# In vsftpd.conf:
# allow_writeable_chroot=NO
# chroot_local_user=YES
# hide_ids=YES
# Symlink following is automatically restricted by chroot

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

from ftplib import FTP, error_perm
from typing import Optional, List
import posixpath
 
class FTPNavigator:
    """
    Robust FTP navigation with proper error handling.
    """
    
    def __init__(self, ftp: FTP):
        self.ftp = ftp
        self._cached_pwd: Optional[str] = None
    
    def get_current_dir(self, use_cache: bool = False) -> str:
        """Get current working directory with optional caching."""
        if use_cache and self._cached_pwd:
            return self._cached_pwd
        
        self._cached_pwd = self.ftp.pwd()
        return self._cached_pwd
    
    def change_dir(self, path: str, create: bool = False) -> bool:
        """
        Change to directory, optionally creating it.
        Returns True on success, False on failure.
        """
        try:
            self.ftp.cwd(path)
            self._cached_pwd = None  # Invalidate cache
            return True
        except error_perm as e:
            if create and '550' in str(e):
                # Directory might not exist - try to create
                return self._create_and_enter(path)
            return False
    
    def _create_and_enter(self, path: str) -> bool:
        """Create directory path and enter it."""
        original = self.get_current_dir()
        
        # Normalize and split path
        parts = path.replace('\\', '/').strip('/').split('/')
        
        current = "" if path.startswith('/') else self.get_current_dir()
        
        for part in parts:
            target = posixpath.join(current, part)
            
            try:
                self.ftp.cwd(target)
                current = target
            except error_perm:
                try:
                    self.ftp.mkd(target)
                    self.ftp.cwd(target)
                    current = target
                except error_perm:
                    # Cannot create - rollback and fail
                    self.ftp.cwd(original)
                    return False
        
        self._cached_pwd = None
        return True
    
    def ensure_dir_exists(self, path: str) -> bool:
        """Check if directory exists, create if not."""
        original = self.get_current_dir()
        
        try:
            self.ftp.cwd(path)
            self.ftp.cwd(original)  # Go back
            return True
        except error_perm:
            result = self._create_and_enter(path)
            if result:
                self.ftp.cwd(original)  # Go back after creation
            return result
    
    def list_directory(self, path: Optional[str] = None, 
                       include_hidden: bool = True) -> List[str]:
        """
        List directory contents with robust parsing.
        """
        files = []
        cmd = 'LIST -la' if include_hidden else 'LIST'
        
        if path:
            cmd = f'{cmd} {path}'
        
        def callback(line):
            # Parse name from LIST output (last whitespace-separated token)
            parts = line.split()
            if len(parts) >= 9:  # Unix-style
                name = ' '.join(parts[8:])  # Handle names with spaces
                # Skip . and ..
                if name not in ('.', '..'):
                    files.append(name)
        
        try:
            self.ftp.retrlines(cmd, callback)
        except error_perm:
            # Fall back to NLST
            files = self.ftp.nlst(path or '')
            files = [f for f in files if f not in ('.', '..')]
        
        return files
    
    def walk(self, path: str = '.'):
        """
        Walk directory tree, yielding (dirpath, dirnames, filenames).
        Similar to os.walk() for local filesystems.
        """
        original = self.get_current_dir()
        
        try:
            self.ftp.cwd(path)
            current = self.get_current_dir()
            
            entries = []
            self.ftp.retrlines('LIST -la', entries.append)
            
            dirs = []
            files = []
            
            for entry in entries:
                parts = entry.split()
                if len(parts) < 9:
                    continue
                
                name = ' '.join(parts[8:])
                if name in ('.', '..'):
                    continue
                
                if entry.startswith('d'):
                    dirs.append(name)
                elif entry.startswith('-') or entry.startswith('l'):
                    files.append(name)
            
            yield (current, dirs, files)
            
            for subdir in dirs:
                # Recursively walk subdirectories
                for item in self.walk(subdir):
                    yield item
                self.ftp.cwd('..')  # Go back up
        
        finally:
            self.ftp.cwd(original)