From 838426b3a4a53f7f91afa59141c5190c72581a34 Mon Sep 17 00:00:00 2001 From: Nicola Murino Date: Thu, 29 Aug 2019 13:52:22 +0200 Subject: [PATCH] improve docs --- README.md | 50 +++++++++++++++++++++++------------------------ scripts/README.md | 21 ++++++++++++-------- 2 files changed, 38 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 661453fe..0667b46c 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,25 @@ # SFTPGo [![Build Status](https://travis-ci.org/drakkan/sftpgo.svg?branch=master)](https://travis-ci.org/drakkan/sftpgo) [![Code Coverage](https://codecov.io/gh/drakkan/sftpgo/branch/master/graph/badge.svg)](https://codecov.io/gh/drakkan/sftpgo/branch/master) [![Go Report Card](https://goreportcard.com/badge/github.com/drakkan/sftpgo)](https://goreportcard.com/report/github.com/drakkan/sftpgo) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) -Full featured and highly configurable SFTP server software +Full featured and highly configurable SFTP server ## Features -- Each account is chrooted to his Home Dir -- SFTP accounts are virtual accounts stored in a "data provider" -- SQLite, MySQL, PostgreSQL and bbolt (key/value store in pure Go) data providers are supported -- Public key and password authentication -- Quota support: accounts can have individual quota expressed as max number of files and max total size -- Bandwidth throttling is supported, with distinct settings for upload and download -- Per user maximum concurrent sessions -- Per user permissions: list directories content, upload, download, delete, rename, create directories, create symlinks can be enabled or disabled -- Per user files/folders ownership: you can map all the users to the system account that runs SFTPGo (all platforms are supported) or you can run SFTPGo as root user and map each user or group of users to a different system account (*NIX only) -- Configurable custom commands and/or HTTP notifications on upload, download, delete or rename -- Automatically terminating idle connections -- Atomic uploads are supported -- Optional SCP support -- REST API for users and quota management and real time reports for the active connections with possibility of forcibly closing a connection -- Log files are accurate and they are saved in the easily parsable JSON format +- Each account is chrooted to his Home Dir. +- SFTP accounts are virtual accounts stored in a "data provider". +- SQLite, MySQL, PostgreSQL and bbolt (key/value store in pure Go) data providers are supported. +- Public key and password authentication. Multiple public keys per user are supported. +- Quota support: accounts can have individual quota expressed as max number of files and/or max total size. +- Bandwidth throttling is supported, with distinct settings for upload and download. +- Per user maximum concurrent sessions. +- Per user permissions: list directories content, upload, download, delete, rename, create directories, create symlinks can be enabled or disabled. +- Per user files/folders ownership: you can map all the users to the system account that runs SFTPGo (all platforms are supported) or you can run SFTPGo as root user and map each user or group of users to a different system account (*NIX only). +- Configurable custom commands and/or HTTP notifications on upload, download, delete or rename. +- Automatically terminating idle connections. +- Atomic uploads are configurable. +- Optional SCP support. +- REST API for users and quota management and real time reports for the active connections with possibility of forcibly closing a connection. +- Log files are accurate and they are saved in the easily parsable JSON format. ## Platforms @@ -28,7 +28,7 @@ Regularly the test cases are manually executed and pass on Windows. Other UNIX v ## Requirements -- Go 1.12 or higher +- Go 1.12 or higher. - A suitable SQL server or key/value store to use as data provider: PostreSQL 9.4+ or MySQL 5.6+ or SQLite 3.x or bbolt 1.3.x ## Installation @@ -92,13 +92,13 @@ Flags: The `serve` subcommand supports the following flags: - `--config-dir` string. Location of the config dir. This directory should contain the `sftpgo` configuration file and is used as the base for files with a relative path (eg. the private keys for the SFTP server, the SQLite or bblot database if you use SQLite or bbolt as data provider). The default value is "." or the value of `SFTPGO_CONFIG_DIR` environment variable. -- `--config-file` string. Name of the configuration file. It must be the name of a file stored in config-dir not the absolute path to the configuration file. The specified file name must have no extension we automatically load JSON, YAML, TOML, HCL and Java properties. The default value is "sftpgo" (and therefore `sftpgo.json`, `sftpgo.yaml` and so on are searched) or the value of `SFTPGO_CONFIG_FILE` environment variable -- `--log-compress` boolean. Determine if the rotated log files should be compressed using gzip. Default `false` or the value of `SFTPGO_LOG_COMPRESS` environment variable (1 or `true`, 0 or `false`) -- `--log-file-path` string. Location for the log file, default "sftpgo.log" or the value of `SFTPGO_LOG_FILE_PATH` environment variable -- `--log-max-age` int. Maximum number of days to retain old log files. Default 28 or the value of `SFTPGO_LOG_MAX_AGE` environment variable -- `--log-max-backups` int. Maximum number of old log files to retain. Default 5 or the value of `SFTPGO_LOG_MAX_BACKUPS` environment variable -- `--log-max-size` int. Maximum size in megabytes of the log file before it gets rotated. Default 10 or the value of `SFTPGO_LOG_MAX_SIZE` environment variable -- `--log-verbose` boolean. Enable verbose logs. Default `true` or the value of `SFTPGO_LOG_VERBOSE` environment variable (1 or `true`, 0 or `false`) +- `--config-file` string. Name of the configuration file. It must be the name of a file stored in config-dir not the absolute path to the configuration file. The specified file name must have no extension we automatically load JSON, YAML, TOML, HCL and Java properties. The default value is "sftpgo" (and therefore `sftpgo.json`, `sftpgo.yaml` and so on are searched) or the value of `SFTPGO_CONFIG_FILE` environment variable. +- `--log-compress` boolean. Determine if the rotated log files should be compressed using gzip. Default `false` or the value of `SFTPGO_LOG_COMPRESS` environment variable (1 or `true`, 0 or `false`). +- `--log-file-path` string. Location for the log file, default "sftpgo.log" or the value of `SFTPGO_LOG_FILE_PATH` environment variable. +- `--log-max-age` int. Maximum number of days to retain old log files. Default 28 or the value of `SFTPGO_LOG_MAX_AGE` environment variable. +- `--log-max-backups` int. Maximum number of old log files to retain. Default 5 or the value of `SFTPGO_LOG_MAX_BACKUPS` environment variable. +- `--log-max-size` int. Maximum size in megabytes of the log file before it gets rotated. Default 10 or the value of `SFTPGO_LOG_MAX_SIZE` environment variable. +- `--log-verbose` boolean. Enable verbose logs. Default `true` or the value of `SFTPGO_LOG_VERBOSE` environment variable (1 or `true`, 0 or `false`). If you don't configure any private host keys, the daemon will use `id_rsa` in the configuration directory. If that file doesn't exist, the daemon will attempt to autogenerate it (if the user that executes SFTPGo has write access to the config-dir). The server supports any private key format supported by [`crypto/ssh`](https://github.com/golang/crypto/blob/master/ssh/keys.go#L32). @@ -340,4 +340,4 @@ Some code was initially taken from [Pterodactyl sftp server](https://github.com/ ## License -GNU GPLv3 +GNU GPLv3 \ No newline at end of file diff --git a/scripts/README.md b/scripts/README.md index 099b00d0..3d70f867 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -22,13 +22,13 @@ python sftpgo_api_cli.py [sub-command] --help Basically there is a sub command for each REST API and the following global arguments: - - `--debug`, default disabled, print useful debug info. - - `--base-url`, default `http://127.0.0.1:8080`. Base URL for SFTPGo REST API - - `--auth-type`, HTTP auth type. Supported HTTP auth type are `basic` and `digest`. Default none - - `--auth-user`, user for HTTP authentication - - `--auth-password`, password for HTTP authentication - - `--insecure`, enable to ignore verifying the SSL certificate. Default disabled - - `--no-color`, disable color highligth for JSON responses. You need python pygments module 1.5 or above for this to work. Default disabled if pygments is found, enabled if not found + - `-d`, `--debug`, default disabled, print useful debug info. + - `-b`, `--base-url`, default `http://127.0.0.1:8080`. Base URL for SFTPGo REST API + - `-a`, `--auth-type`, HTTP auth type. Supported HTTP auth type are `basic` and `digest`. Default none + - `-u`, `--auth-user`, user for HTTP authentication + - `-p`, `--auth-password`, password for HTTP authentication + - `-i`, `--insecure`, enable to ignore verifying the SSL certificate. Default disabled + - `-t`, `--no-color`, disable color highligth for JSON responses. You need python pygments module 1.5 or above for this to work. Default disabled if pygments is found, enabled if not found. Please read the note at the end of this doc for colors in Windows command prompt. For each subcommand `--help` shows the available arguments, try for example: @@ -265,4 +265,9 @@ Output: "build_date": "2019-08-08T08:11:34Z", "commit_hash": "4f4489d-dirty" } -``` \ No newline at end of file +``` + +### Colors highlight for Windows command prompt + +If your Windows command prompt does not recognize ANSI/VT100 escape sequences you can download [ANSICON](https://github.com/adoxa/ansicon "ANSICON") extract proper files depending on your Windows OS, and install them using `ansicon -i`. +Thats all. From now on, your Windows command prompt will be aware of ANSI colors. \ No newline at end of file