sftpgo/docs/custom-actions.md

Custom Actions

The actions struct inside the "sftpd" configuration section allows to configure the actions for file operations and SSH commands.

Actions will not be executed if an error is detected, and so a partial file is uploaded or an SSH command is not successfully completed. The upload condition includes both uploads to new files and overwrite of existing files. The ssh_cmd condition will be triggered after a command is successfully executed via SSH. scp will trigger the download and upload conditions and not ssh_cmd.

The command, if defined, is invoked with the following arguments:

• action, string, possible values are: download, upload, delete, rename, ssh_cmd
• username
• path is the full filesystem path, can be empty for some ssh commands
• target_path, non empty for rename action
• ssh_cmd, non empty for ssh_cmd action

The command can also read the following environment variables:

• SFTPGO_ACTION
• SFTPGO_ACTION_USERNAME
• SFTPGO_ACTION_PATH
• SFTPGO_ACTION_TARGET, non empty for rename SFTPGO_ACTION
• SFTPGO_ACTION_SSH_CMD, non empty for ssh_cmd SFTPGO_ACTION
• SFTPGO_ACTION_FILE_SIZE, non empty for upload, download and delete SFTPGO_ACTION
• SFTPGO_ACTION_LOCAL_FILE, true if the affected file is stored on the local filesystem, otherwise false

Previous global environment variables aren't cleared when the script is called. The command must finish within 30 seconds.

The http_notification_url, if defined, will contain the following, percent encoded, query string parameters:

• action
• username
• path
• local_file, true if the affected file is stored on the local filesystem, otherwise false
• target_path, added for rename action
• ssh_cmd, added for ssh_cmd action
• file_size, added for upload, download, delete actions

The HTTP request is executed with a 15-second timeout.

The actions struct inside the "data_provider" configuration section allows you to configure actions on user add, update, delete.

Actions will not be fired for internal updates, such as the last login or the user quota fields, or after external authentication.

The command, if defined, is invoked with the following arguments:

• action, string, possible values are: add, update, delete
• username
• ID
• status
• expiration_date
• home_dir
• uid
• gid

The command can also read the following environment variables:

• SFTPGO_USER_ACTION
• SFTPGO_USER_USERNAME
• SFTPGO_USER_PASSWORD, hashed password as stored inside the data provider, can be empty if the user does not login using a password
• SFTPGO_USER_ID
• SFTPGO_USER_STATUS
• SFTPGO_USER_EXPIRATION_DATE
• SFTPGO_USER_HOME_DIR
• SFTPGO_USER_UID
• SFTPGO_USER_GID
• SFTPGO_USER_QUOTA_FILES
• SFTPGO_USER_QUOTA_SIZE
• SFTPGO_USER_UPLOAD_BANDWIDTH
• SFTPGO_USER_DOWNLOAD_BANDWIDTH
• SFTPGO_USER_MAX_SESSIONS
• SFTPGO_USER_FS_PROVIDER

Previous global environment variables aren't cleared when the script is called. The command must finish within 15 seconds.

The http_notification_url, if defined, will be called invoked as http POST. The action is added to the query string, for example <http_notification_url>?action=update, and the user is sent serialized as JSON inside the POST body with sensitive fields removed.

The HTTP request is executed with a 15-second timeout.