deblan-mirror/sftpgo
1
0
Fork 0
mirror of https://github.com/drakkan/sftpgo.git synced 2024-06-02 16:32:17 +02:00
Code Issues Packages Projects Releases Wiki Activity
sftpgo/httpd/schema/openapi.yaml

1876 lines
60 KiB
YAML
Raw Normal View History

first version
2019-07-20 12:26:52 +02:00
openapi: 3.0.1
info:
title: SFTPGo
description: 'SFTPGo REST API'
refactoring: add common package The common package defines the interfaces that a protocol must implement and contain code that can be shared among supported protocols. This way should be easier to support new protocols
2020-07-24 23:39:38 +02:00
version: 1.9.2
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
first version
2019-07-20 12:26:52 +02:00
servers:
- url: /api/v1
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
security:
- BasicAuth: []
first version
2019-07-20 12:26:52 +02:00
paths:
add version info
2019-08-08 10:01:33 +02:00
/version:
get:
tags:
- version
summary: Get version details
operationId: get_version
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/VersionInfo'
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
httpd: add an API to get data provider status
2019-11-14 18:48:01 +01:00
/providerstatus:
get:
tags:
- providerstatus
summary: Get data provider status
operationId: get_provider_status
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 200
message: "Alive"
error: ""
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
httpd: add an API to get data provider status
2019-11-14 18:48:01 +01:00
500:
description: Provider Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
/connection:
first version
2019-07-20 12:26:52 +02:00
get:
tags:
- connections
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
summary: Get the active users and info about their uploads/downloads
operationId: get_connections
first version
2019-07-20 12:26:52 +02:00
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/ConnectionStatus'
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
/connection/{connectionID}:
first version
2019-07-20 12:26:52 +02:00
delete:
tags:
- connections
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
summary: Terminate an active connection
operationId: close_connection
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
parameters:
first version
2019-07-20 12:26:52 +02:00
- name: connectionID
in: path
description: ID of the connection to close
required: true
schema:
type: string
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 200
message: "Connection closed"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
/quota_scan:
get:
tags:
- quota
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
summary: Get the active quota scans for users home directories
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 22:42:46 +02:00
operationId: get_quota_scans
first version
2019-07-20 12:26:52 +02:00
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/QuotaScan'
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
post:
tags:
- quota
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
summary: start a new user quota scan
description: A quota scan update the number of files and their total size for the specified user
first version
2019-07-20 12:26:52 +02:00
operationId: start_quota_scan
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
201:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 201
message: "Scan started"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 404
message: ""
error: "Error description if any"
409:
description: Another scan is already in progress for this user
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 409
message: "Another scan is already in progress"
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
Add API endpoint to set current quota Fixes #130
2020-06-20 12:38:04 +02:00
/quota_update:
put:
tags:
- quota
summary: update the user used quota limits
description: Set the current used quota limits for the given user
operationId: quota_update
parameters:
- in: query
name: mode
required: false
description: the update mode specifies if the given quota usage values should be added or replace the current ones
schema:
type: string
enum: [add, reset]
description: >
Update type:
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example: reset
requestBody:
required: true
description: The only user mandatory fields are username,used_quota_size and used_quota_files. Please note that if the quota fields are missing they will default to 0
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 200
message: "Quota updated"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
409:
description: A quota scan is in progress for this user
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 409
message: "A quota scan is in progress"
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
/folder_quota_update:
put:
tags:
- quota
summary: update the folder used quota limits
description: Set the current used quota limits for the given folder
operationId: folder_quota_update
parameters:
- in: query
name: mode
required: false
description: the update mode specifies if the given quota usage values should be added or replace the current ones
schema:
type: string
enum: [add, reset]
description: >
Update type:
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example: reset
requestBody:
required: true
description: The only folder mandatory fields are mapped_path,used_quota_size and used_quota_files. Please note that if the used quota fields are missing they will default to 0
content:
application/json:
schema:
$ref : '#/components/schemas/BaseVirtualFolder'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 200
message: "Quota updated"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
409:
description: A quota scan is in progress for this folder
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 409
message: "A quota scan is in progress"
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
/folder_quota_scan:
get:
tags:
- quota
summary: Get the active quota scans for folders
operationId: get_folders_quota_scans
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/FolderQuotaScan'
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
post:
tags:
- quota
summary: start a new folder quota scan
description: A quota scan update the number of files and their total size for the specified folder
operationId: start_folder_quota_scan
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/BaseVirtualFolder'
responses:
201:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 201
message: "Scan started"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
409:
description: Another scan is already in progress for this user
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 409
message: "Another scan is already in progress"
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
/folder:
get:
tags:
- folders
summary: Returns an array with one or more folders
operationId: get_folders
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
required: false
description: The maximum number of items to return. Max value is 500, default is 100
- in: query
name: order
required: false
description: Ordering folders by path. Default ASC
schema:
type: string
enum:
- ASC
- DESC
example: ASC
- in: query
name: folder_path
required: false
description: Filter by folder path, extact match case sensitive
schema:
type: string
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/BaseVirtualFolder'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
post:
tags:
- folders
summary: Adds a new folder
operationId: add_folder
description: a new folder with the specified mapped_path will be added. To update the used quota parameters a quota scan is needed
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/BaseVirtualFolder'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/BaseVirtualFolder'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
delete:
tags:
- folders
summary: Delete an existing folder
operationId: delete_folder
parameters:
- name: folder_path
in: query
description: path to the folder to delete
required: true
schema:
type: string
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
example:
status: 200
message: "Folder deleted"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
/user:
get:
tags:
- users
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
summary: Returns an array with one or more users
add a basic web interface The builtin web interface allows to manage users and connections
2019-10-07 18:19:01 +02:00
description: For security reasons hashed passwords are omitted in the response
first version
2019-07-20 12:26:52 +02:00
operationId: get_users
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
required: false
description: The maximum number of items to return. Max value is 500, default is 100
- in: query
name: order
required: false
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
description: Ordering users by username. Default ASC
first version
2019-07-20 12:26:52 +02:00
schema:
type: string
enum:
- ASC
- DESC
example: ASC
- in: query
name: username
required: false
description: Filter by username, extact match case sensitive
schema:
type: string
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/User'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
post:
tags:
- users
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
summary: Adds a new user
first version
2019-07-20 12:26:52 +02:00
operationId: add_user
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/User'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
/user/{userID}:
get:
tags:
- users
summary: Find user by ID
add a basic web interface The builtin web interface allows to manage users and connections
2019-10-07 18:19:01 +02:00
description: For security reasons the hashed password is omitted in the response
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 22:42:46 +02:00
operationId: get_user_by_id
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
parameters:
first version
2019-07-20 12:26:52 +02:00
- name: userID
in: path
description: ID of the user to retrieve
required: true
schema:
type: integer
format: int32
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/User'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
put:
tags:
- users
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 22:42:46 +02:00
summary: Update an existing user
operationId: update_user
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
parameters:
first version
2019-07-20 12:26:52 +02:00
- name: userID
in: path
description: ID of the user to update
required: true
schema:
type: integer
format: int32
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 200
message: "User updated"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
delete:
tags:
- users
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 22:42:46 +02:00
summary: Delete an existing user
operationId: delete_user
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
parameters:
first version
2019-07-20 12:26:52 +02:00
- name: userID
in: path
description: ID of the user to delete
required: true
schema:
type: integer
format: int32
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 200
message: "User deleted"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
example:
first version
2019-07-20 12:26:52 +02:00
status: 500
message: ""
error: "Error description if any"
add backup/restore REST API
2019-12-27 23:12:44 +01:00
/dumpdata:
get:
tags:
- maintenance
summary: Backup SFTPGo data serializing them as JSON
description: The backup is saved to a local file to avoid to expose users hashed passwords over the network. The output of dumpdata can be used as input for loaddata
operationId: dumpdata
parameters:
- in: query
name: output_file
schema:
type: string
required: true
description: Path for the file to write the JSON serialized data to. This path is relative to the configured "backups_path". If this file already exists it will be overwritten
memory provider: load users from a dump file The `memory` provider can load users from a dump obtained using the `dumpdata` REST API. This dump file can be configured using the dataprovider `name` configuration key. It will be loaded at startup and can be reloaded on demand using a `SIGHUP` on Unix based systems and a `paramchange` request to the running service on Windows. Fixes #66
2020-02-02 22:20:39 +01:00
- in: query
name: indent
schema:
type: integer
enum:
- 0
- 1
description: >
indent:
* `0` no indentation. This is the default
* `1` format the output JSON
add backup/restore REST API
2019-12-27 23:12:44 +01:00
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
example:
status: 200
message: "Data saved"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
add backup/restore REST API
2019-12-27 23:12:44 +01:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
/loaddata:
get:
tags:
- maintenance
summary: Restore SFTPGo data from a JSON backup
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
description: Users and folders will be restored one by one and the restore is stopped if a user/folder cannot be added or updated, so it could happen a partial restore
add backup/restore REST API
2019-12-27 23:12:44 +01:00
operationId: loaddata
parameters:
- in: query
name: input_file
schema:
type: string
required: true
description: Path for the file to read the JSON serialized data from. This can be an absolute path or a path relative to the configured "backups_path". The max allowed file size is 10MB
- in: query
name: scan_quota
schema:
type: integer
enum:
- 0
- 1
- 2
description: >
Quota scan:
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
* `0` no quota scan is done, the imported users will have used_quota_size and used_quota_files = 0 or the existing values if they already exists. This is the default
add backup/restore REST API
2019-12-27 23:12:44 +01:00
* `1` scan quota
* `2` scan quota if the user has quota restrictions
required: false
loaddata: add an option that allows to not modify existing users
2020-01-31 19:10:45 +01:00
- in: query
name: mode
schema:
type: integer
enum:
- 0
- 1
description: >
Mode:
* `0` New users are added, existing users are updated. This is the default
* `1` New users are added, existing users are not modified
add backup/restore REST API
2019-12-27 23:12:44 +01:00
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
example:
status: 200
message: "Data restored"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 401
message: ""
error: "Error description if any"
add backup/restore REST API
2019-12-27 23:12:44 +01:00
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
first version
2019-07-20 12:26:52 +02:00
components:
schemas:
Permission:
type: string
enum:
- '*'
- list
- download
- upload
add a new permission for overwriting existing files The upload permission is required to allow file overwrite
2019-09-17 08:53:45 +02:00
- overwrite
first version
2019-07-20 12:26:52 +02:00
- delete
- rename
- create_dirs
- create_symlinks
sftpd: add support for chmod/chown added matching permissions too and a new setting "setstat_mode". Setting setstat_mode to 1 you can keep the previous behaviour that silently ignore setstat requests
2019-11-15 12:15:07 +01:00
- chmod
- chown
sftpd: add support for chtimes This improve rclone compatibility
2019-11-16 10:23:41 +01:00
- chtimes
first version
2019-07-20 12:26:52 +02:00
description: >
Permissions:
set version to 0.9.2
2019-09-18 22:19:34 +02:00
* `*` - all permissions are granted
first version
2019-07-20 12:26:52 +02:00
* `list` - list items is allowed
* `download` - download files is allowed
* `upload` - upload files is allowed
add a new permission for overwriting existing files The upload permission is required to allow file overwrite
2019-09-17 08:53:45 +02:00
* `overwrite` - overwrite an existing file, while uploading, is allowed. upload permission is required to allow file overwrite
first version
2019-07-20 12:26:52 +02:00
* `delete` - delete files or directories is allowed
* `rename` - rename files or directories is allowed
* `create_dirs` - create directories is allowed
* `create_symlinks` - create links is allowed
sftpd: add support for chmod/chown added matching permissions too and a new setting "setstat_mode". Setting setstat_mode to 1 you can keep the previous behaviour that silently ignore setstat requests
2019-11-15 12:15:07 +01:00
* `chmod` changing file or directory permissions is allowed
* `chown` changing file or directory owner and group is allowed
sftpd: add support for chtimes This improve rclone compatibility
2019-11-16 10:23:41 +01:00
* `chtimes` changing file or directory access and modification time is allowed
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 18:20:19 +01:00
DirPermissions:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/Permission'
minItems: 1
minProperties: 1
description: hash map with directory as key and an array of permissions as value. Directories must be absolute paths, permissions for root directory ("/") are required
add support for per user authentication methods You can, for example, deny one or more authentication methods to one or more users.
2020-02-19 22:39:30 +01:00
LoginMethods:
type: string
enum:
- 'publickey'
- 'password'
- 'keyboard-interactive'
add support for partial authentication Multi-step authentication is activated disabling all single-step auth methods for a given user
2020-04-09 23:32:42 +02:00
- 'publickey+password'
- 'publickey+keyboard-interactive'
filters: we can now set allowed and denied files extensions
2020-03-01 22:10:29 +01:00
ExtensionsFilter:
type: object
properties:
path:
type: string
description: SFTP/SCP path, if no other specific filter is defined, the filter apply for sub directories too. For example if filters are defined for the paths "/" and "/sub" then the filters for "/" are applied for any file outside the "/sub" directory
allowed_extensions:
type: array
items:
type: string
nullable: true
description: list of, case insensitive, allowed files extension. Shell like expansion is not supported so you have to specify `.jpg` and not `*.jpg`
example: [ ".jpg", ".png" ]
denied_extensions:
type: array
items:
type: string
nullable: true
description: list of, case insensitive, denied files extension. Denied file extensions are evaluated before the allowed ones
example: [ ".zip" ]
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 18:37:50 +01:00
UserFilters:
type: object
properties:
allowed_ip:
type: array
items:
type: string
nullable: true
description: only clients connecting from these IP/Mask are allowed. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32"
example: [ "192.0.2.0/24", "2001:db8::/32" ]
denied_ip:
type: array
items:
type: string
nullable: true
description: clients connecting from these IP/Mask are not allowed. Denied rules are evaluated before allowed ones
example: [ "172.16.0.0/16" ]
add support for per user authentication methods You can, for example, deny one or more authentication methods to one or more users.
2020-02-19 22:39:30 +01:00
denied_login_methods:
type: array
items:
$ref: '#/components/schemas/LoginMethods'
nullable: true
description: if null or empty any available login method is allowed
filters: we can now set allowed and denied files extensions
2020-03-01 22:10:29 +01:00
file_extensions:
type: array
items:
$ref: '#/components/schemas/ExtensionsFilter'
nullable: true
description: filters based on file extensions. These restrictions do not apply to files listing for performance reasons, so a denied file cannot be downloaded/overwritten/renamed but it will still be listed in the list of files. Please note that these restrictions can be easily bypassed
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
description: Additional restrictions
S3Config:
type: object
properties:
bucket:
type: string
minLength: 1
region:
type: string
minLength: 1
access_key:
type: string
minLength: 1
access_secret:
type: string
minLength: 1
description: the access secret is stored encrypted (AES-256-GCM)
endpoint:
type: string
description: optional endpoint
storage_class:
type: string
s3: add documentation and test cases for upload part size
2020-03-13 17:28:55 +01:00
upload_part_size:
type: integer
description: the buffer size (in MB) to use for multipart uploads. The minimum allowed part size is 5MB, and if this value is set to zero, the default value (5MB) for the AWS SDK will be used. The minimum allowed value is 5.
upload_concurrency:
type: integer
s3: upload concurrency is now configurable Please note that if the upload bandwidth between the SFTP client and SFTPGo is greater than the upload bandwidth between SFTPGo and S3 then the SFTP client have to wait for the upload of the last parts to S3 after it ends the file upload to SFTPGo, and it may time out. Keep this in mind if you customize parts size and upload concurrency
2020-03-13 19:13:58 +01:00
description: the number of parts to upload in parallel. If this value is set to zero, the default value (2) will be used
S3: add support for serving virtual folders inside the same bucket each user can be assigned to a virtual folder. This is similar to a chroot directory for local filesystem
2020-01-19 23:23:09 +01:00
key_prefix:
type: string
description: key_prefix is similar to a chroot directory for a local filesystem. If specified the SFTP user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole bucket contents will be available
example: folder/subfolder/
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
required:
- bucket
- region
nullable: true
description: S3 Compatible Object Storage configuration details
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 19:04:00 +01:00
GCSConfig:
type: object
properties:
bucket:
type: string
minLength: 1
credentials:
type: string
format: byte
pre-login program: allow to create a new user too clarify the difference between dynamic user creation/update and external authentication
2020-03-27 23:26:22 +01:00
description: Google Cloud Storage JSON credentials base64 encoded. This field must be populated only when adding/updating a user. It will be always omitted, since there are sensitive data, when you search/get users. The credentials will be stored in the configured "credentials_path"
gcs: add support for automatic credentials We can now also support implicit credentials using the Application Default Credentials strategy
2020-02-19 09:41:15 +01:00
automatic_credentials:
type: integer
nullable: true
enum:
- 0
- 1
description: >
Automatic credentials:
* `0` - disabled, explicit credentials, using a JSON credentials file, must be provided. This is the default value if the field is null
* `1` - enabled, we try to use the Application Default Credentials (ADC) strategy to find your application's credentials
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 19:04:00 +01:00
storage_class:
type: string
key_prefix:
type: string
description: key_prefix is similar to a chroot directory for a local filesystem. If specified the SFTP user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole bucket contents will be available
example: folder/subfolder/
required:
- bucket
nullable: true
description: Google Cloud Storage configuration details
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
FilesystemConfig:
type: object
properties:
provider:
type: integer
enum:
- 0
- 1
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 19:04:00 +01:00
- 2
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
description: >
Providers:
* `0` - local filesystem
* `1` - S3 Compatible Object Storage
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 19:04:00 +01:00
* `2` - Google Cloud Storage
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
s3config:
$ref: '#/components/schemas/S3Config'
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 19:04:00 +01:00
gcsconfig:
$ref: '#/components/schemas/GCSConfig'
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
description: Storage filesystem details
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
BaseVirtualFolder:
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 11:30:26 +01:00
type: object
properties:
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
id:
type: integer
format: int32
minimum: 1
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 11:30:26 +01:00
mapped_path:
type: string
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
description: absolute filesystem path to use as virtual folder. This field is unique
used_quota_size:
type: integer
format: int64
used_quota_files:
type: integer
format: int32
last_quota_update:
type: integer
format: int64
description: Last quota update as unix timestamp in milliseconds
users:
type: array
sftpd: add support for excluding virtual folders from user quota limit Fixes #110
2020-05-01 15:27:53 +02:00
nullable: true
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
items:
type: string
description: list of usernames associated with this virtual folder
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 11:30:26 +01:00
required:
- mapped_path
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
description: defines the path for the virtual folder and the used quota limits. The same folder can be shared among multiple users and each user can have different quota limits or a different virtual path.
VirtualFolder:
allOf:
- $ref: '#/components/schemas/BaseVirtualFolder'
- type: object
properties:
virtual_path:
type: string
quota_size:
type: integer
format: int64
description: Quota as size in bytes. 0 menas unlimited, -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
quota_files:
type: integer
format: int32
description: Quota as number of files. 0 menas unlimited, , -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
required:
- virtual_path
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 11:30:26 +01:00
description: A virtual folder is a mapping between a SFTP/SCP virtual path and a filesystem path outside the user home directory. The specified paths must be absolute and the virtual path cannot be "/", it must be a sub directory. The parent directory for the specified virtual path must exist. SFTPGo will try to automatically create any missing parent directory for the configured virtual folders at user login.
first version
2019-07-20 12:26:52 +02:00
User:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
status:
type: integer
enum:
- 0
- 1
description: >
status:
* `0` user is disabled, login is not allowed
* `1` user is enabled
first version
2019-07-20 12:26:52 +02:00
username:
type: string
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
description: username is unique
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
expiration_date:
type: integer
format: int64
description: expiration date as unix timestamp in milliseconds. An expired account cannot login. 0 means no expiration
first version
2019-07-20 12:26:52 +02:00
password:
type: string
nullable: true
sftpd: add support for SSH user certificate authentication This add support for PROTOCOL.certkeys vendor extension: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?rev=1.8 Fixes #117 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2020-05-15 20:08:53 +02:00
description: password or public key/SSH user certificate are mandatory. If the password has no known hashing algo prefix it will be stored using argon2id. You can send a password hashed as bcrypt or pbkdf2 and it will be stored as is. For security reasons this field is omitted when you search/get users
rename public_key in public_keys remove compatibility layer to convert public keys newline delimited in json list
2019-08-07 23:41:10 +02:00
public_keys:
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 22:42:46 +02:00
type: array
items:
type: string
first version
2019-07-20 12:26:52 +02:00
nullable: true
sftpd: add support for SSH user certificate authentication This add support for PROTOCOL.certkeys vendor extension: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?rev=1.8 Fixes #117 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2020-05-15 20:08:53 +02:00
description: a password or at least one public key/SSH user certificate are mandatory.
first version
2019-07-20 12:26:52 +02:00
home_dir:
type: string
description: path to the user home directory. The user cannot upload or download files outside this directory. SFTPGo tries to automatically create this folder if missing. Must be an absolute path
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 11:30:26 +01:00
virtual_folders:
type: array
items:
$ref: '#/components/schemas/VirtualFolder'
nullable: true
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
description: mapping between virtual SFTP/SCP paths and filesystem paths outside the user home directory. Supported for local filesystem only. If one or more of the specified folders are not inside the dataprovider they will be automatically created. You have to create the folder on the filesystem yourself
first version
2019-07-20 12:26:52 +02:00
uid:
type: integer
format: int32
minimum: 0
maximum: 65535
description: if you run sftpgo as root user the created files and directories will be assigned to this uid. 0 means no change, the owner will be the user that runs sftpgo. Ignored on windows
gid:
type: integer
format: int32
minimum: 0
maximum: 65535
description: if you run sftpgo as root user the created files and directories will be assigned to this gid. 0 means no change, the group will be the one of the user that runs sftpgo. Ignored on windows
max_sessions:
type: integer
format: int32
pre-login program: allow to create a new user too clarify the difference between dynamic user creation/update and external authentication
2020-03-27 23:26:22 +01:00
description: Limit the sessions that a user can open. 0 means unlimited
first version
2019-07-20 12:26:52 +02:00
quota_size:
type: integer
format: int64
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 18:37:50 +01:00
description: Quota as size in bytes. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
first version
2019-07-20 12:26:52 +02:00
quota_files:
type: integer
format: int32
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 18:37:50 +01:00
description: Quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
first version
2019-07-20 12:26:52 +02:00
permissions:
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 18:20:19 +01:00
type: object
first version
2019-07-20 12:26:52 +02:00
items:
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 18:20:19 +01:00
$ref: '#/components/schemas/DirPermissions'
first version
2019-07-20 12:26:52 +02:00
minItems: 1
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 18:20:19 +01:00
example: {"/":["*"],"/somedir":["list","download"]}
first version
2019-07-20 12:26:52 +02:00
used_quota_size:
type: integer
format: int64
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
used_quota_files:
first version
2019-07-20 12:26:52 +02:00
type: integer
format: int32
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 19:29:32 +02:00
last_quota_update:
first version
2019-07-20 12:26:52 +02:00
type: integer
format: int64
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 18:37:50 +01:00
description: Last quota update as unix timestamp in milliseconds
first version
2019-07-20 12:26:52 +02:00
upload_bandwidth:
type: integer
format: int32
description: Maximum upload bandwidth as KB/s, 0 means unlimited
download_bandwidth:
type: integer
format: int32
description: Maximum download bandwidth as KB/s, 0 means unlimited
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
last_login:
type: integer
format: int64
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 18:37:50 +01:00
description: Last user login as unix timestamp in milliseconds
filters:
$ref: '#/components/schemas/UserFilters'
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 07:41:05 +01:00
filesystem:
$ref: '#/components/schemas/FilesystemConfig'
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
Transfer:
first version
2019-07-20 12:26:52 +02:00
type: object
properties:
operation_type:
type: string
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 11:36:21 +01:00
enum:
first version
2019-07-20 12:26:52 +02:00
- upload
- download
sftpd stats: add file path for active upload/download
2019-08-08 19:33:16 +02:00
path:
type: string
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
description: file path for the upload/download
first version
2019-07-20 12:26:52 +02:00
start_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 19:29:32 +02:00
description: start time as unix timestamp in milliseconds
first version
2019-07-20 12:26:52 +02:00
size:
type: integer
format: int64
description: bytes transferred
ConnectionStatus:
type: object
properties:
username:
type: string
description: connected username
connection_id:
type: string
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
description: unique connection identifier
first version
2019-07-20 12:26:52 +02:00
client_version:
type: string
refactoring: add common package The common package defines the interfaces that a protocol must implement and contain code that can be shared among supported protocols. This way should be easier to support new protocols
2020-07-24 23:39:38 +02:00
nullable: true
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
description: client version
first version
2019-07-20 12:26:52 +02:00
remote_address:
type: string
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
description: Remote address for the connected client
first version
2019-07-20 12:26:52 +02:00
connection_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 19:29:32 +02:00
description: connection time as unix timestamp in milliseconds
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
ssh_command:
type: string
refactoring: add common package The common package defines the interfaces that a protocol must implement and contain code that can be shared among supported protocols. This way should be easier to support new protocols
2020-07-24 23:39:38 +02:00
nullable: true
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
description: SSH command. This is not empty for protocol SSH
first version
2019-07-20 12:26:52 +02:00
last_activity:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 19:29:32 +02:00
description: last client activity as unix timestamp in milliseconds
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
protocol:
type: string
enum:
- SFTP
- SCP
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 23:30:37 +01:00
- SSH
first version
2019-07-20 12:26:52 +02:00
active_transfers:
type: array
refactoring: add common package The common package defines the interfaces that a protocol must implement and contain code that can be shared among supported protocols. This way should be easier to support new protocols
2020-07-24 23:39:38 +02:00
nullable: true
first version
2019-07-20 12:26:52 +02:00
items:
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 14:41:15 +02:00
$ref : '#/components/schemas/Transfer'
first version
2019-07-20 12:26:52 +02:00
QuotaScan:
type: object
properties:
username:
type: string
description: username with an active scan
start_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 19:29:32 +02:00
description: scan start time as unix timestamp in milliseconds
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
FolderQuotaScan:
type: object
properties:
mapped_path:
type: string
description: path with an active scan
start_time:
type: integer
format: int64
description: scan start time as unix timestamp in milliseconds
first version
2019-07-20 12:26:52 +02:00
ApiResponse:
type: object
properties:
status:
type: integer
format: int32
minimum: 200
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 23:30:18 +02:00
maximum: 509
first version
2019-07-20 12:26:52 +02:00
example: 200
description: HTTP Status code, for example 200 OK, 400 Bad request and so on
message:
type: string
nullable: true
description: additional message if any
error:
type: string
nullable: true
description: error description if any
add version info
2019-08-08 10:01:33 +02:00
VersionInfo:
type: object
properties:
version:
type: string
build_date:
type: string
commit_hash:
type: string
add support for build tag to allow to disable some features The following build tags are available: - "nogcs", disable Google Cloud Storage backend - "nos3", disable S3 Compabible Object Storage backends - "nobolt", disable Bolt data provider - "nomysql", disable MySQL data provider - "nopgsql", disable PostgreSQL data provider - "nosqlite", disable SQLite data provider - "noportable", disable portable mode
2020-05-23 11:58:05 +02:00
features:
type: array
items:
type: string
description: Features for the current build. Available features are "portable", "bolt", "mysql", "sqlite", "pgsql", "s3", "gcs". If a feature is available it has a "+" prefix, otherwise a "-" prefix
httpd: add support for basic auth and HTTPS
2020-02-04 00:08:00 +01:00
securitySchemes:
BasicAuth:
type: http
scheme: basic
Reference in a new issue Copy permalink