Nicola Murino 4a88ea5c03 add Data At Rest Encryption support преди 4 години
..
README.md 4a88ea5c03 add Data At Rest Encryption support преди 4 години
sftpgo_api_cli 4a88ea5c03 add Data At Rest Encryption support преди 4 години

README.md

REST API CLI client

sftpgo_api_cli is a very simple command line client for SFTPGo REST API written in python.

It has the following requirements:

  • python3 or python2
  • python Requests module
  • Optionally, if the python module Pygments 1.5 or above is installed, the JSON responses will be highlighted with colors.

You can see the usage with the following command:

python sftpgo_api_cli --help

and

python sftpgo_api_cli [sub-command] --help

Basically there is a sub command for each REST API and the following global arguments:

  • -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 and you aren't on Windows, otherwise enabled.
  • -c, --color, enable color highligth for JSON responses. You need python pygments module 1.5 or above for this to work. Default enabled if pygments is found and you aren't on Windows, otherwise disabled. 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:


Additionally it can convert users to the SFTPGo format from some supported users stores

Let's see a sample usage for each REST API.

## Add user

Command:

console python sftpgo_api_cli add-user test_username --password "test_pwd" --home-dir="/tmp/test_home_dir" --uid 33 --gid 1000 --max-sessions 2 --quota-size 0 --quota-files 3 --permissions "list" "download" "upload" "delete" "rename" "create_dirs" "overwrite" --subdirs-permissions "/dir1::list,download" "/dir2::" --upload-bandwidth 100 --download-bandwidth 60 --status 0 --expiration-date 2019-01-01 --allowed-ip "192.168.1.1/32" --fs S3 --s3-bucket test --s3-region eu-west-1 --s3-access-key accesskey --s3-access-secret secret --s3-endpoint "http://127.0.0.1:9000" --s3-storage-class Standard --s3-key-prefix "vfolder/" --s3-upload-part-size 10 --s3-upload-concurrency 4 --denied-login-methods "password" "keyboard-interactive" --allowed-patterns "/dir1::.jpg,.png" "/dir2::.rar,.png" --denied-patterns "/dir3::.zip,*.rar" --denied-protocols DAV FTP --additional-info "sample info"


Output:

json { "additional_info": "sample info", "download_bandwidth": 60, "expiration_date": 1546297200000, "filesystem": {

"azblobconfig": {
  "account_key": {}
},
"cryptconfig": {
  "passphrase": {}
},
"gcsconfig": {
  "credentials": {}
},
"provider": 1,
"s3config": {
  "access_key": "accesskey",
  "access_secret": {
    "payload": "ALVIG4egZxRjKH8/8NsJViA7EH5MqsweqmwLhGj4M4AGYgMM2ygF7kbCw+R5aQ==",
    "status": "Secretbox"
  },
  "bucket": "test",
  "endpoint": "http://127.0.0.1:9000",
  "key_prefix": "vfolder/",
  "region": "eu-west-1",
  "storage_class": "Standard",
  "upload_concurrency": 4,
  "upload_part_size": 10
}

}, "filters": {

"allowed_ip": [
  "192.168.1.1/32"
],
"denied_login_methods": [
  "password",
  "keyboard-interactive"
],
"denied_protocols": [
  "DAV",
  "FTP"
],
"file_patterns": [
  {
    "allowed_patterns": [
      "*.jpg",
      "*.png"
    ],
    "path": "/dir1"
  },
  {
    "allowed_patterns": [
      "*.rar",
      "*.png"
    ],
    "path": "/dir2"
  },
  {
    "denied_patterns": [
      "*.zip",
      "*.rar"
    ],
    "path": "/dir3"
  }
]

}, "gid": 1000, "home_dir": "/tmp/test_home_dir", "id": 9576, "last_login": 0, "last_quota_update": 0, "max_sessions": 2, "permissions": {

"/": [
  "list",
  "download",
  "upload",
  "delete",
  "rename",
  "create_dirs",
  "overwrite"
],
"/dir1": [
  "list",
  "download"
],
"/dir2": [
  "*"
]

}, "quota_files": 3, "quota_size": 0, "status": 0, "uid": 33, "upload_bandwidth": 100, "used_quota_files": 0, "used_quota_size": 0, "username": "test_username" }


## Update user

Command:

console python sftpgo_api_cli update-user 9576 test_username --password "test_pwd" --home-dir="/tmp/test_home_dir" --uid 0 --gid 33 --max-sessions 3 --quota-size 0 --quota-files 4 --permissions "*" --subdirs-permissions "/dir1::list,download,create_symlinks" --upload-bandwidth 90 --download-bandwidth 80 --status 1 --expiration-date "" --allowed-ip "" --denied-ip "192.168.1.0/24" --denied-login-methods "" --fs local --virtual-folders "/vdir1::/tmp/mapped1::-1::-1" "/vdir2::/tmp/mapped2::100::104857600" --allowed-patterns "" --denied-patterns "" --max-upload-file-size 104857600 --denied-protocols ""


Output:

json { "error": "", "message": "User updated", "status": 200 }


You can set the argument `--disconnect` to `1` to disconnect the user, if connected, after a successful update and so force it to login again and to use the new configuration. If this parameter is not specified the user will continue to use the old configuration as long as he is logged in.

## Get user by id

Command:

console python sftpgo_api_cli get-user-by-id 9576


Output:

json { "download_bandwidth": 80, "expiration_date": 0, "filesystem": {

"azblobconfig": {
  "account_key": {}
},
"cryptconfig": {
  "passphrase": {}
},
"gcsconfig": {
  "credentials": {}
},
"provider": 0,
"s3config": {
  "access_secret": {}
}

}, "filters": {

"denied_ip": [
  "192.168.1.0/24"
],
"max_upload_file_size": 104857600

}, "gid": 33, "home_dir": "/tmp/test_home_dir", "id": 9576, "last_login": 0, "last_quota_update": 0, "max_sessions": 3, "permissions": {

"/": [
  "*"
],
"/dir1": [
  "list",
  "download",
  "create_symlinks"
]

}, "quota_files": 4, "quota_size": 0, "status": 1, "uid": 0, "upload_bandwidth": 90, "used_quota_files": 0, "used_quota_size": 0, "username": "test_username", "virtual_folders": [

{
  "id": 1,
  "last_quota_update": 0,
  "mapped_path": "/tmp/mapped1",
  "quota_files": -1,
  "quota_size": -1,
  "used_quota_files": 0,
  "used_quota_size": 0,
  "virtual_path": "/vdir1"
},
{
  "id": 2,
  "last_quota_update": 0,
  "mapped_path": "/tmp/mapped2",
  "quota_files": 100,
  "quota_size": 104857600,
  "used_quota_files": 0,
  "used_quota_size": 0,
  "virtual_path": "/vdir2"
}

] }


## Get users

Command:

console python sftpgo_api_cli get-users --limit 1 --offset 0 --username test_username --order DESC


Output:

json [ {

"download_bandwidth": 80,
"expiration_date": 0,
"filesystem": {
  "azblobconfig": {
    "account_key": {}
  },
  "gcsconfig": {
    "credentials": {}
  },
  "provider": 0,
  "s3config": {
    "access_secret": {}
  }
},
"filters": {
  "denied_ip": [
    "192.168.1.0/24"
  ],
  "max_upload_file_size": 104857600
},
"gid": 33,
"home_dir": "/tmp/test_home_dir",
"id": 9576,
"last_login": 0,
"last_quota_update": 0,
"max_sessions": 3,
"permissions": {
  "/": [
    "*"
  ],
  "/dir1": [
    "list",
    "download",
    "create_symlinks"
  ]
},
"quota_files": 4,
"quota_size": 0,
"status": 1,
"uid": 0,
"upload_bandwidth": 90,
"used_quota_files": 0,
"used_quota_size": 0,
"username": "test_username",
"virtual_folders": [
  {
    "exclude_from_quota": false,
    "mapped_path": "/tmp/mapped1",
    "virtual_path": "/vdir1"
  },
  {
    "exclude_from_quota": true,
    "mapped_path": "/tmp/mapped2",
    "virtual_path": "/vdir2"
  }
]

} ]


## Get active connections

Command:

console python sftpgo_api_cli get-connections


Output:

json [ {

"active_transfers": [
  {
    "operation_type": "upload",
    "path": "/test_upload.tar.gz",
    "size": 1540096,
    "start_time": 1577197471372
  }
],
"client_version": "SSH-2.0-OpenSSH_8.1",
"connection_id": "f82cfec6a391ad673edd4ae9a144f32ccb59456139f8e1185b070134fffbab7c",
"connection_time": 1577197433003,
"last_activity": 1577197485561,
"protocol": "SFTP",
"remote_address": "127.0.0.1:43714",
"username": "test_username"

} ]


## Get folders

Command:

console python sftpgo_api_cli get-folders --limit 1 --offset 0 --folder-path /tmp/mapped1 --order DESC


Output:

json [ {

"id": 1,
"last_quota_update": 1591563422870,
"mapped_path": "/tmp/mapped1",
"used_quota_files": 1,
"used_quota_size": 13313790,
"users": [
  "test_username"
]

} ]


## Add folder

console python sftpgo_api_cli add-folder /tmp/mapped_folder


Output:

json { "id": 4, "last_quota_update": 0, "mapped_path": "/tmp/mapped_folder", "used_quota_files": 0, "used_quota_size": 0 }


## Close connection

Command:

console python sftpgo_api_cli close-connection f82cfec6a391ad673edd4ae9a144f32ccb59456139f8e1185b070134fffbab7c


Output:

json { "error": "", "message": "Connection closed", "status": 200 }


## Get quota scans

Command:

console python sftpgo_api_cli get-quota-scans


## Start quota scan

Command:

console python sftpgo_api_cli start-quota-scan test_username


Output:

json { "status": 201, "message": "Scan started", "error": "" }


## Get folder quota scans

Command:

console python sftpgo_api_cli get-folders-quota-scans


## Start folder quota scan

Command:

console python sftpgo_api_cli start-folder-quota-scan /tmp/mapped_folder


Output:

json { "status": 201, "message": "Scan started", "error": "" }


## Update quota usage

Command:

console python sftpgo_api_cli -d update-quota-usage a -S 123 -F 1 -M reset


Output:

json { "error": "", "message": "Quota updated", "status": 200 }


## Update folder quota usage

Command:

console python sftpgo_api_cli -d update-quota-usage /tmp/mapped_folder -S 123 -F 1 -M add


Output:

json { "error": "", "message": "Quota updated", "status": 200 }


## Delete user

Command:

console python sftpgo_api_cli delete-user 9576


Output:

json { "error": "", "message": "User deleted", "status": 200 }


## Delete folder

console python sftpgo_api_cli delete-folder /tmp/mapped_folder


Output:

json { "error": "", "message": "Folder deleted", "status": 200 }


## Get version

Command:

console python sftpgo_api_cli get-version


Output:

json { "build_date": "2019-12-24T14:17:47Z", "commit_hash": "f8fd5c0-dirty", "version": "0.9.4-dev" }


## Get provider status

Command:

console python sftpgo_api_cli get-provider-status


Output:

json { "error": "", "message": "Alive", "status": 200 }


## Backup data

Command:

console python sftpgo_api_cli dumpdata backup.json --indent 1


Output:

json { "error": "", "message": "Data saved", "status": 200 }


## Restore data

Command:

console python sftpgo_api_cli loaddata /app/data/backups/backup.json --scan-quota 2 --mode 0


Output:

json { "error": "", "message": "Data restored", "status": 200 }


## Convert users from other stores

You can convert users to the SFTPGo format from the following users stores:

- Linux users stored in `shadow`/`passwd` files
- Pure-FTPd virtual users generated using `pure-pw` CLI
- ProFTPD users generated using `ftpasswd` CLI

For details give a look at the `convert-users` subcommand usage:

console python sftpgo_api_cli convert-users --help


Let's see some examples:

console python sftpgo_api_cli convert-users "" unix-passwd unix_users.json --min-uid 500 --force-uid 1000 --force-gid 1000


console python sftpgo_api_cli convert-users pureftpd.passwd pure-ftpd pure_users.json --usernames "user1" "user2"


console python sftpgo_api_cli convert-users proftpd.passwd proftpd pro_users.json ```

The json file generated using the convert-users subcommand can be used as input for the loaddata subcommand.

Please note that when importing Linux/Unix users the input file is not required: /etc/passwd and /etc/shadow are automatically parsed. /etc/shadow read permission is is typically granted to the root user, so you need to execute the convert-users subcommand as root.

Colors highlight for Windows command prompt

If your Windows command prompt does not recognize ANSI/VT100 escape sequences you can download 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.