go/sftpgo
1
0
Fork 0
mirror of https://github.com/drakkan/sftpgo.git synced 2025-11-23 22:04:50 +02:00
Code Issues Releases Activity

docs: fix markdown lint warnings

Browse Source
This commit is contained in:
Nicola Murino
2020-06-15 23:46:11 +02:00
parent 37418a7630
commit c491133aff
16 changed files with 105 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/custom-actions.md
View File

@@ -44,7 +44,6 @@ If the `hook` defines an HTTP URL then this URL will be invoked as HTTP POST. Th
- `endpoint`, not null for S3 backend if configured
- `status`, integer. 0 means an error occurred. 1 means no error
The HTTP request will use the global configuration for HTTP clients.
The `actions` struct inside the "data_provider" configuration section allows you to configure actions on user add, update, delete.

3
docs/dynamic-user-mod.md
View File

@@ -35,7 +35,7 @@ In other words while using "External Authentication" the external program receiv
Let's see a very basic example. Our sample program will grant access to the existing user `test_user` only in the time range 10:00-18:00. Other users will not be modified since the program will terminate with no output.
```
```shell
#!/bin/bash
CURRENT_TIME=`date +%H:%M`
@@ -51,4 +51,3 @@ fi
```
Please note that this is a demo program and it might not work in all cases. For example, the username should be obtained by parsing the JSON serialized user and not by searching the username inside the JSON as shown here.

2
docs/external-auth.md
View File

@@ -37,7 +37,7 @@ You can combine the scopes. For example, 3 means password and public key, 5 mean
Let's see a very basic example. Our sample authentication program will only accept user `test_user` with any password or public key.
```
```shell
#!/bin/sh
if test "$SFTPGO_AUTHD_USERNAME" = "test_user"; then

2
docs/full-configuration.md
View File

@@ -4,7 +4,7 @@
The SFTPGo executable can be used this way:
```
```console
Usage:
sftpgo [command]

16
docs/keyboard-interactive.md
View File

@@ -29,7 +29,7 @@ The authentication must finish within 60 seconds.
Let's see a very basic example. Our sample keyboard interactive authentication program will ask for 2 sets of questions and accept the user if the answer to the last question is `answer3`.
```
```shell
#!/bin/sh
echo '{"questions":["Question1: ","Question2: "],"instruction":"This is a sample for keyboard interactive authentication","echos":[true,false]}'
@@ -50,7 +50,7 @@ fi
and here is an example where SFTPGo checks the user password for you:
```
```shell
#!/bin/sh
echo '{"questions":["Password: "],"instruction":"This is a sample for keyboard interactive authentication","echos":[false],"check_password":1}'
@@ -85,7 +85,7 @@ The HTTP response code must be 200 and the body must contain the same JSON struc
Let's see a basic sample, the configured hook is `http://127.0.0.1:8000/keyIntHookPwd`, as soon as the user try to login, SFTPGo makes this HTTP POST request:
```
```shell
POST /keyIntHookPwd HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: Go-http-client/1.1
@@ -100,7 +100,7 @@ as you can see in this first requests `answers` and `questions` are null.
Here is the response that instructs SFTPGo to ask for the user password and to check it:
```
```shell
HTTP/1.1 200 OK
Date: Tue, 31 Mar 2020 21:15:24 GMT
Server: WSGIServer/0.2 CPython/3.8.2
@@ -113,7 +113,7 @@ Content-Length: 143
The user enters the correct password and so SFTPGo makes a new HTTP POST, please note that the `request_id` is the same of the previous request, this time the asked `questions` and the user's `answers` are not null:
```
```shell
POST /keyIntHookPwd HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: Go-http-client/1.1
@@ -126,7 +126,7 @@ Accept-Encoding: gzip
Here is the HTTP response that istructs SFTPGo to ask for a new question:
```
```shell
HTTP/1.1 200 OK
Date: Tue, 31 Mar 2020 21:15:27 GMT
Server: WSGIServer/0.2 CPython/3.8.2
@@ -139,7 +139,7 @@ Content-Length: 66
As soon as the user answer to this question, SFTPGo will make a new HTTP POST request with the user's answers:
```
```shell
POST /keyIntHookPwd HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: Go-http-client/1.1
@@ -152,7 +152,7 @@ Accept-Encoding: gzip
Here is the final HTTP response that allows the user login:
```
```shell
HTTP/1.1 200 OK
Date: Tue, 31 Mar 2020 21:15:29 GMT
Server: WSGIServer/0.2 CPython/3.8.2

11
docs/performance.md
View File

@@ -3,13 +3,16 @@
SFTPGo can easily saturate a Gigabit connection on low end hardware with no special configuration, this is generally enough for most use cases.
For Multi-Gig connections, some performance improvements and comparisons with OpenSSH have been discussed [here](https://github.com/drakkan/sftpgo/issues/69), most of them have been included in the master branch. To summarize:
- In current state with all performance improvements applied, SFTP performance is very close to OpenSSH however CPU usage is higher. SCP performance match OpenSSH.
- The main bottlenecks are the encryption and the messages authentication, so if you can use a fast cipher with implicit messages authentication, such as `aes128-gcm@openssh.com`, you will get a big performance boost.
- SCP protocol is much simpler than SFTP and so, the multi-platform, SFTPGo's SCP implementation performs better than SFTP.
- Load balancing with HAProxy can greatly improve the performance if CPU not become the bottleneck.
## Benchmark
### Hardware specification
**Server** ||
--- | --- |
OS| Debian 10.2 x64 |
@@ -41,6 +44,7 @@ Server's CPU is in Eco mode, you can expect better results in certain cases with
The Message Authentication Code (MAC) used is `hmac-sha2-256`.
##### SFTP
Download:
Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
@@ -62,6 +66,7 @@ Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
8|605|1210|1368|1273|1820|
##### SCP
Download:
Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
@@ -87,6 +92,7 @@ Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
With this cipher the messages authentication is implicit, no SHA256 computation is needed.
##### SFTP
Download:
Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
@@ -108,6 +114,7 @@ Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
8|1042|1578|<--|1433|1893|
##### SCP
Download:
Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
@@ -129,14 +136,14 @@ Stream|Baseline MB/s|Devel MB/s|Optimized MB/s|Balanced MB/s|OpenSSH MB/s|
8|1733|1744|<--|1664|2510|
### Optimizations applied
- AES-CTR optimization of Go compiler for x86_64, there is a [patch](https://go-review.googlesource.com/c/go/+/51670) that hasn't been merged yet, you can apply it yourself.
- AES-CTR optimization of Go compiler for x86_64, there is a [patch](https://go-review.googlesource.com/c/go/+/51670) that hasn't been merged yet, you can apply it yourself.
### HAProxy configuration
Here is the relevant HAProxy configuration used for the `Balanced` test configuration:
```
```console
frontend sftp
bind :2222
mode tcp

5
docs/portable-mode.md
View File

@@ -2,7 +2,7 @@
SFTPGo allows to share a single directory on demand using the `portable` subcommand:
```
```console
sftpgo portable --help
To serve the current working directory with auto generated credentials simply use:
@@ -49,11 +49,10 @@ In portable mode, SFTPGo can advertise the SFTP service and, optionally, the cre
Here is an example of the advertised service including credentials as seen using `avahi-browse`:
```
```console
= enp0s31f6 IPv4 SFTPGo portable 53705 SFTP File Transfer local
hostname = [p1.local]
address = [192.168.1.230]
port = [53705]
txt = ["password=EWOo6pJe" "user=user" "version=0.9.3-dev-b409523-dirty-2019-10-26T13:43:32Z"]
```

4
docs/rest-api.md
View File

@@ -8,14 +8,14 @@ REST API can be protected using HTTP basic authentication and exposed via HTTPS.
For example, you can keep SFTPGo listening on localhost and expose it externally configuring a reverse proxy using Apache HTTP Server this way:
```
```shell
ProxyPass /api/v1 http://127.0.0.1:8080/api/v1
ProxyPassReverse /api/v1 http://127.0.0.1:8080/api/v1
```
and you can add authentication with something like this:
```
```shell
<Location /api/v1>
AuthType Digest
AuthName "Private"

1
docs/s3.md
View File

@@ -3,6 +3,7 @@
To connect SFTPGo to AWS, you need to specify credentials, a `bucket` and a `region`. Here is the list of available [AWS regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). For example, if your bucket is at `Frankfurt`, you have to set the region to `eu-central-1`. You can specify an AWS [storage class](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html) too. Leave it blank to use the default AWS storage class. An endpoint is required if you are connecting to a Compatible AWS Storage such as [MinIO](https://min.io/).
AWS SDK has different options for credentials. [More Detail](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html). We support:
1. Providing [Access Keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
2. Use IAM roles for Amazon EC2
3. Use IAM roles for tasks if your application uses an ECS task definition