sftpgo-mirror/examples/rest-api-cli/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:

python sftpgo_api_cli add_user --help

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:

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-extensions "/dir1::.jpg,.png" "/dir2::.rar,.png" --denied-extensions "/dir3::.zip,.rar" --denied-protocols DAV FTP

Output:

{
  "download_bandwidth": 60,
  "expiration_date": 1546297200000,
  "filesystem": {
    "gcsconfig": {},
    "provider": 1,
    "s3config": {
      "access_key": "accesskey",
      "access_secret": "$aes$6c088ba12b0b261247c8cf331c46d9260b8e58002957d89ad1c0495e3af665cd0227",
      "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_extensions": [
      {
        "allowed_extensions": [
          ".jpg",
          ".png"
        ],
        "path": "/dir1"
      },
      {
        "allowed_extensions": [
          ".rar",
          ".png"
        ],
        "path": "/dir2"
      },
      {
        "denied_extensions": [
          ".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:

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-extensions "" --denied-extensions "" --max-upload-file-size 104857600 --denied-protocols ""

Output:

{
  "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:

python sftpgo_api_cli get-user-by-id 9576

Output:

{
  "download_bandwidth": 80,
  "expiration_date": 0,
  "filesystem": {
    "gcsconfig": {},
    "provider": 0,
    "s3config": {}
  },
  "filters": {
    "denied_ip": [
      "192.168.1.0/24"
    ],
    "file_extensions": [
      {
        "allowed_extensions": [
          ".jpg",
          ".png"
        ],
        "path": "/dir1"
      },
      {
        "allowed_extensions": [
          ".rar",
          ".png"
        ],
        "path": "/dir2"
      },
      {
        "denied_extensions": [
          ".zip",
          ".rar"
        ],
        "path": "/dir3"
      }
    ],
    "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:

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

Output:

[
  {
    "download_bandwidth": 80,
    "expiration_date": 0,
    "filesystem": {
      "gcsconfig": {},
      "provider": 0,
      "s3config": {}
    },
    "filters": {
      "denied_ip": [
        "192.168.1.0/24"
      ]
    },
    "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:

python sftpgo_api_cli get-connections

Output:

[
  {
    "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:

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

Output:

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

Add folder

python sftpgo_api_cli add-folder /tmp/mapped_folder

Output:

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

Close connection

Command:

python sftpgo_api_cli close-connection f82cfec6a391ad673edd4ae9a144f32ccb59456139f8e1185b070134fffbab7c

Output:

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

Get quota scans

Command:

python sftpgo_api_cli get-quota-scans

Start quota scan

Command:

python sftpgo_api_cli start-quota-scan test_username

Output:

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

Get folder quota scans

Command:

python sftpgo_api_cli get-folders-quota-scans

Start folder quota scan

Command:

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

Output:

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

Update quota usage

Command:

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

Output:

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

Update folder quota usage

Command:

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

Output:

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

Delete user

Command:

python sftpgo_api_cli delete-user 9576

Output:

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

Delete folder

python sftpgo_api_cli delete-folder /tmp/mapped_folder

Output:

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

Get version

Command:

python sftpgo_api_cli get-version

Output:

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

Get provider status

Command:

python sftpgo_api_cli get-provider-status

Output:

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

Backup data

Command:

python sftpgo_api_cli dumpdata backup.json --indent 1

Output:

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

Restore data

Command:

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

Output:

{
  "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:

python sftpgo_api_cli convert-users --help

Let's see some examples:

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

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

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.