Signals

Django FTP Server provides Django signals that are emitted when various FTP events occur. This allows you to hook into FTP server events for logging, auditing, or custom processing.

Available Signals

All signals are defined in django_ftpserver.signals.

Connection Signals

ftp_server_started

Sent when the FTP server starts.

Arguments:

sender: The command class
server: The FTPServer instance
host: Server host address
port: Server port number

ftp_server_stopped

Sent when the FTP server stops.

Arguments:

sender: The command class
server: The FTPServer instance
host: Server host address
port: Server port number

ftp_client_connected

Sent when a client connects to the server.

Arguments:

sender: The handler class
handler: The FTPHandler instance
remote_ip: Client IP address
remote_port: Client port number

ftp_client_disconnected

Sent when a client disconnects from the server.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username (if authenticated, otherwise None)
remote_ip: Client IP address

Authentication Signals

ftp_login

Sent when a user successfully logs in.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
remote_ip: Client IP address

ftp_login_failed

Sent when a login attempt fails.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Attempted username
remote_ip: Client IP address

ftp_logout

Sent when a user logs out.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
remote_ip: Client IP address

File Transfer Signals

ftp_file_received

Sent when a file upload completes successfully.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: File path
remote_ip: Client IP address

ftp_file_sent

Sent when a file download completes successfully.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: File path
remote_ip: Client IP address

ftp_file_received_incomplete

Sent when a file upload is interrupted.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: File path
remote_ip: Client IP address

ftp_file_sent_incomplete

Sent when a file download is interrupted.

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: File path
remote_ip: Client IP address

File Operation Signals

ftp_file_deleted

Sent when a file is deleted (DELE command).

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: Deleted file path
remote_ip: Client IP address

ftp_file_renamed

Sent when a file or directory is renamed (RNFR/RNTO commands).

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path_from: Original path
path_to: New path
remote_ip: Client IP address

ftp_directory_created

Sent when a directory is created (MKD command).

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: Created directory path
remote_ip: Client IP address

ftp_directory_deleted

Sent when a directory is deleted (RMD command).

Arguments:

sender: The handler class
handler: The FTPHandler instance
username: Username
path: Deleted directory path
remote_ip: Client IP address

Usage Examples

Basic Signal Receiver

Create a file receivers.py in your Django app:

import logging
from django.dispatch import receiver
from django_ftpserver.signals import ftp_login, ftp_logout, ftp_login_failed

logger = logging.getLogger('ftp.access')

@receiver(ftp_login)
def log_ftp_login(sender, username, remote_ip, **kwargs):
    logger.info("FTP login: user=%s, ip=%s", username, remote_ip)

@receiver(ftp_logout)
def log_ftp_logout(sender, username, remote_ip, **kwargs):
    logger.info("FTP logout: user=%s, ip=%s", username, remote_ip)

@receiver(ftp_login_failed)
def log_ftp_login_failed(sender, username, remote_ip, **kwargs):
    logger.warning("FTP login failed: user=%s, ip=%s", username, remote_ip)

Make sure to import your receivers in your app’s apps.py:

from django.apps import AppConfig

class MyAppConfig(AppConfig):
    name = 'myapp'

    def ready(self):
        import myapp.receivers  # noqa

File Upload Processing

Process uploaded files (e.g., virus scanning, thumbnail generation):

from django.dispatch import receiver
from django_ftpserver.signals import ftp_file_received

@receiver(ftp_file_received)
def process_uploaded_file(sender, username, path, **kwargs):
    # Queue async task for heavy processing
    from myapp.tasks import process_file
    process_file.delay(path, username)

Audit Logging

Store FTP events in a database for auditing:

from django.dispatch import receiver
from django_ftpserver.signals import (
    ftp_login, ftp_logout,
    ftp_file_received, ftp_file_sent, ftp_file_deleted
)
from myapp.models import FTPAuditLog

@receiver(ftp_login)
def audit_login(sender, username, remote_ip, **kwargs):
    FTPAuditLog.objects.create(
        event_type='login',
        username=username,
        remote_ip=remote_ip,
    )

@receiver(ftp_file_received)
def audit_upload(sender, username, path, remote_ip, **kwargs):
    FTPAuditLog.objects.create(
        event_type='upload',
        username=username,
        remote_ip=remote_ip,
        path=path,
    )

@receiver(ftp_file_deleted)
def audit_delete(sender, username, path, remote_ip, **kwargs):
    FTPAuditLog.objects.create(
        event_type='delete',
        username=username,
        remote_ip=remote_ip,
        path=path,
    )

Debug Logging

The FTP handlers emit DEBUG level logs for all events. You can enable these logs in your Django settings:

LOGGING = {
    'version': 1,
    'handlers': {
        'console': {'class': 'logging.StreamHandler'},
    },
    'loggers': {
        'django_ftpserver.handlers': {
            'handlers': ['console'],
            'level': 'DEBUG',
        },
    },
}

To disable the debug logs, set the level to INFO or higher:

LOGGING = {
    'version': 1,
    'loggers': {
        'django_ftpserver.handlers': {
            'level': 'INFO',
        },
    },
}

Handler Classes

To use signals, make sure you are using the Django FTP handlers. By default, the management command uses these handlers automatically.

Available handlers:

django_ftpserver.handlers.DjangoFTPHandler - FTP handler with signal support
django_ftpserver.handlers.DjangoTLS_FTPHandler - TLS FTP handler with signal support (requires pyOpenSSL)

You can also specify custom handlers in your Django settings:

FTPSERVER_HANDLER = 'django_ftpserver.handlers.DjangoFTPHandler'
FTPSERVER_TLSHANDLER = 'django_ftpserver.handlers.DjangoTLS_FTPHandler'