beenull/sftpgo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sftpgo/docs/custom-actions.md

88 lines
4.6 KiB
Markdown
Raw Normal View History

Refactor docs
2020-03-04 22:10:58 +00:00
# Custom Actions
The `actions` struct inside the "sftpd" configuration section allows to configure the actions for file operations and SSH commands.
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
The `hook` can be defined as the absolute path of your program or an HTTP URL.
Refactor docs
2020-03-04 22:10:58 +00:00
quota: improve size check get the remaining allowed size when an upload starts and check it against the uploaded bytes Fixes #128
2020-06-18 20:38:03 +00:00
The `upload` condition includes both uploads to new files and overwrite of existing files. If an upload is aborted for quota limits SFTPGo tries to remove the partial file, so if the notification reports a zero size file and a quota exceeded error the file has been deleted. 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`.
sftpd actions: execute defined command on error too add a new field inside the notification to indicate if an error is detected
2020-04-03 17:25:38 +00:00
The notification will indicate if an error is detected and so, for example, a partial file is uploaded.
sftpd actions: add support for pre-delete action Fixes #121
2020-05-24 21:31:14 +00:00
The `pre-delete` action, if defined, will be called just before files deletion. If the external command completes with a zero exit status or the HTTP notification response code is `200` then SFTPGo will assume that the file was already deleted/moved and so it will not try to remove the file and it will not execute the hook defined for the `delete` action.
Refactor docs
2020-03-04 22:10:58 +00:00
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
If the `hook` defines a path to an external program, then this program is invoked with the following arguments:
Refactor docs
2020-03-04 22:10:58 +00:00
sftpd actions: add support for pre-delete action Fixes #121
2020-05-24 21:31:14 +00:00
- `action`, string, possible values are: `download`, `upload`, `pre-delete`,`delete`, `rename`, `ssh_cmd`
Refactor docs
2020-03-04 22:10:58 +00:00
- `username`
- `path` is the full filesystem path, can be empty for some ssh commands
ssh commands: add sftpgo-copy and sftpgo-remove Fixes #122
2020-06-13 20:48:51 +00:00
- `target_path`, non-empty for `rename` action and for `sftpgo-copy` SSH command
file actions: add bucket and endpoint to notifications The HTTP notifications are now invoked as POST and the notification is a JSON inside the POST body. This is a backward incompatible change but this way the actions can be extended more easily, sorry for the trouble Fixes #101
2020-03-25 17:36:33 +00:00
- `ssh_cmd`, non-empty for `ssh_cmd` action
Refactor docs
2020-03-04 22:10:58 +00:00
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
The external program can also read the following environment variables:
Refactor docs
2020-03-04 22:10:58 +00:00
- `SFTPGO_ACTION`
- `SFTPGO_ACTION_USERNAME`
- `SFTPGO_ACTION_PATH`
file actions: add bucket and endpoint to notifications The HTTP notifications are now invoked as POST and the notification is a JSON inside the POST body. This is a backward incompatible change but this way the actions can be extended more easily, sorry for the trouble Fixes #101
2020-03-25 17:36:33 +00:00
- `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_FS_PROVIDER`, `0` for local filesystem, `1` for S3 backend, `2` for Google Cloud Storage (GCS) backend
- `SFTPGO_ACTION_BUCKET`, non-empty for S3 and GCS backends
- `SFTPGO_ACTION_ENDPOINT`, non-empty for S3 backend if configured
quota: improve size check get the remaining allowed size when an upload starts and check it against the uploaded bytes Fixes #128
2020-06-18 20:38:03 +00:00
- `SFTPGO_ACTION_STATUS`, integer. 0 means a generic error occurred. 1 means no error, 2 means quota exceeded error
Refactor docs
2020-03-04 22:10:58 +00:00
Previous global environment variables aren't cleared when the script is called.
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
The program must finish within 30 seconds.
Refactor docs
2020-03-04 22:10:58 +00:00
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
If the `hook` defines an HTTP URL then this URL will be invoked as HTTP POST. The request body will contain a JSON serialized struct with the following fields:
Refactor docs
2020-03-04 22:10:58 +00:00
- `action`
- `username`
- `path`
file actions: add bucket and endpoint to notifications The HTTP notifications are now invoked as POST and the notification is a JSON inside the POST body. This is a backward incompatible change but this way the actions can be extended more easily, sorry for the trouble Fixes #101
2020-03-25 17:36:33 +00:00
- `target_path`, not null for `rename` action
- `ssh_cmd`, not null for `ssh_cmd` action
- `file_size`, not null for `upload`, `download`, `delete` actions
- `fs_provider`, `0` for local filesystem, `1` for S3 backend, `2` for Google Cloud Storage (GCS) backend
- `bucket`, not null for S3 and GCS backends
- `endpoint`, not null for S3 backend if configured
quota: improve size check get the remaining allowed size when an upload starts and check it against the uploaded bytes Fixes #128
2020-06-18 20:38:03 +00:00
- `status`, integer. 0 means a generic error occurred. 1 means no error, 2 means quota exceeded error
file actions: add bucket and endpoint to notifications The HTTP notifications are now invoked as POST and the notification is a JSON inside the POST body. This is a backward incompatible change but this way the actions can be extended more easily, sorry for the trouble Fixes #101
2020-03-25 17:36:33 +00:00
add a new configuration section for HTTP clients HTTP clients are used for executing hooks such as the ones used for custom actions, external authentication and pre-login user modifications. This allows, for example, to use self-signed certificate without defeating the purpose of using TLS
2020-04-26 21:29:09 +00:00
The HTTP request will use the global configuration for HTTP clients.
Refactor docs
2020-03-04 22:10:58 +00:00
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.
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
If the `hook` defines a path to an external program, then this program is invoked with the following arguments:
Refactor docs
2020-03-04 22:10:58 +00:00
- `action`, string, possible values are: `add`, `update`, `delete`
- `username`
- `ID`
- `status`
- `expiration_date`
- `home_dir`
- `uid`
- `gid`
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
The external program can also read the following environment variables:
Refactor docs
2020-03-04 22:10:58 +00:00
- `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.
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
The program must finish within 15 seconds.
Refactor docs
2020-03-04 22:10:58 +00:00
actions: add a generic hook to define external commands and HTTP URL We can only define a single hook now and it can be an HTTP notification or an external command, not both
2020-05-24 13:29:39 +00:00
If the `hook` defines an HTTP URL then this URL will be invoked as HTTP POST. The action is added to the query string, for example `<hook>?action=update`, and the user is sent serialized as JSON inside the POST body with sensitive fields removed.
Refactor docs
2020-03-04 22:10:58 +00:00
add a new configuration section for HTTP clients HTTP clients are used for executing hooks such as the ones used for custom actions, external authentication and pre-login user modifications. This allows, for example, to use self-signed certificate without defeating the purpose of using TLS
2020-04-26 21:29:09 +00:00
The HTTP request will use the global configuration for HTTP clients.
Reference in a new issue Copy permalink