diff --git a/docs/en-US/getting-started/connecting.md b/docs/en-US/getting-started/connecting.md index b22abf4..74d72a4 100644 --- a/docs/en-US/getting-started/connecting.md +++ b/docs/en-US/getting-started/connecting.md @@ -1 +1,77 @@ # Connecting to a server + +termscp can start in three different ways depending on the arguments you pass. + +- No arguments: termscp opens the authentication form, where you provide the + parameters required to connect to the remote host. +- An address argument: termscp skips the authentication form and connects + directly to the remote host. +- A bookmark name with `-b, --address-as-bookmark`: termscp resolves the + argument as a saved bookmark and connects. + +When you provide an address argument or a bookmark name, you can also provide a +start working directory for the local host. + +## The authentication form + +When termscp starts without an address, it shows the authentication form. Fill +in the protocol, address, port, username, and password, then connect. termscp +will open the dual-pane explorer once the connection succeeds. + +## Address argument syntax + +The generic address argument has the following syntax: + +```txt +[protocol://][username@]
[:port][:wrkdir] +``` + +This syntax is convenient, and you will probably use it instead of the +interactive form. Here are some examples. + +Connect using the default protocol (defined in your configuration) to +`192.168.1.31`. If the port is not provided, the default port for the selected +protocol is used. The username is the current user's name. + +```sh +termscp 192.168.1.31 +``` + +Connect using the default protocol to `192.168.1.31` as user `root`: + +```sh +termscp root@192.168.1.31 +``` + +Connect using SCP to `192.168.1.31` on port `4022` as user `omar`: + +```sh +termscp scp://omar@192.168.1.31:4022 +``` + +Connect using SCP to `192.168.1.31` on port `4022` as user `omar`, starting in +directory `/tmp`: + +```sh +termscp scp://omar@192.168.1.31:4022:/tmp +``` + +For protocol-specific address syntax (S3, Kube, WebDAV, and SMB), see +[Connection parameters](connection-parameters.md). + +## How the password is provided + +When you provide the address as an argument, there is no field for the password +in the address itself. You can provide the password in three ways: + +- You will be prompted for it. This is the default: if you don't use any of the + methods below, termscp prompts for the password, like classic tools such as + `scp` and `ssh`. +- `-P, --password` option: pass the password directly on the command line. This + method is discouraged because it is insecure: the password may be kept in + your shell history. +- Via `sshpass`: provide the password through `sshpass`, for example: + + ```sh + sshpass -f ~/.ssh/topsecret.key termscp cvisintin@192.168.1.31 + ``` diff --git a/docs/en-US/getting-started/connection-parameters.md b/docs/en-US/getting-started/connection-parameters.md index 3fc529b..4ee675b 100644 --- a/docs/en-US/getting-started/connection-parameters.md +++ b/docs/en-US/getting-started/connection-parameters.md @@ -1 +1,168 @@ # Connection parameters + +Each protocol has its own set of authentication-form fields and its own +command-line address syntax. This page describes them protocol by protocol. + +## SFTP / SCP + +Authentication-form fields: + +- Host (address) +- Port (default `22`) +- Username +- Password or SSH key + +You can authenticate either with a username and password or with an SSH key. +See [SSH key storage](../configuration/ssh-keys.md) for how to manage keys. + +Address syntax: + +```txt +[protocol://][username@]
[:port][:wrkdir] +``` + +## FTP / FTPS + +Authentication-form fields: + +- Host (address) +- Port (default `21`) +- Username +- Password +- Secure (FTPS): enable TLS to use FTPS instead of plain FTP + +Address syntax: + +```txt +[protocol://][username@]
[:port][:wrkdir] +``` + +## Kube + +Authentication-form fields: + +- Namespace +- Cluster URL (Kubernetes API URL) +- Username +- Client certificate path +- Client key path + +Address syntax: + +```txt +kube://[namespace][@][$] +``` + +## S3 + +termscp supports both AWS S3 and other S3-compatible endpoints. + +Authentication-form fields: + +- Bucket name +- Region (for AWS S3) or endpoint (for other S3-compatible servers) +- Profile +- Access key +- Secret access key +- Security token +- Session token +- New path style + +The required and optional fields differ depending on the endpoint: + +- AWS S3: + - bucket name (required) + - region (required) + - profile (optional; defaults to `default`) + - access key (required unless the bucket is public) + - secret access key (required unless the bucket is public) + - security token (if required) + - session token (if required) + - new path style: NO +- Other S3 endpoints: + - bucket name (required) + - endpoint (required) + - access key (required unless the bucket is public) + - secret access key (required unless the bucket is public) + - new path style: YES + +Address syntax: + +```txt +s3://@[:profile][:/wrkdir] +``` + +For example: + +```txt +s3://buckethead@eu-central-1:default:/assets +``` + +### S3 credentials + +To connect to an AWS S3 bucket you must provide credentials. There are three +ways to do this. + +1. Authentication form: provide the access key (usually mandatory), the secret + access key (usually mandatory), the security token, and the session token. + If you save the S3 connection as a bookmark, the access key and secret access + key are saved as an encrypted AES-256/BASE64 string in your bookmarks file. + The security token and session token are not saved, since they are meant to + be temporary credentials. +2. Credentials file: configure the AWS CLI with `aws configure`. Your + credentials are then stored at `~/.aws/credentials`. If you use a profile + other than `default`, provide it in the profile field of the authentication + form. +3. Environment variables: provide your credentials as environment variables. + These always override the credentials in the credentials file. The following + are usually mandatory: + + - `AWS_ACCESS_KEY_ID`: AWS access key ID (usually starts with `AKIA...`) + - `AWS_SECRET_ACCESS_KEY`: the secret access key + + If you have configured stronger security, you may also need: + + - `AWS_SECURITY_TOKEN`: security token + - `AWS_SESSION_TOKEN`: session token + +Your credentials are safe: termscp does not manipulate these values directly. +They are consumed directly by the `s3` crate. + +## SMB + +Authentication-form fields: + +- Server (address) +- Share +- Username +- Password +- Port (other systems only; default `445`) +- Workgroup (other systems only) + +On Windows the port and workgroup fields are not used. + +Windows address syntax: + +```txt +\\[username@]\[\path\...] +``` + +Other systems address syntax: + +```txt +smb://[username@][:port]/[/path/.../] +``` + +## WebDAV + +Authentication-form fields: + +- URI (the base WebDAV endpoint) +- Username +- Password + +Address syntax: + +```txt +http(s)://:@ +``` diff --git a/docs/en-US/getting-started/installation.md b/docs/en-US/getting-started/installation.md index 25267fe..bb35efb 100644 --- a/docs/en-US/getting-started/installation.md +++ b/docs/en-US/getting-started/installation.md @@ -1 +1,83 @@ # Installation + +termscp is available for many platforms. Pick the method that matches your +system below. + +## Linux, FreeBSD, and macOS + +This shell script installs termscp on your system with a single command: + +```sh +curl --proto '=https' --tlsv1.2 -sSLf https://termscp.rs/install.sh | sh +``` + +On macOS the installation requires [Homebrew](https://brew.sh/); otherwise the +Rust compiler is installed to build termscp from source. + +## Windows + +Install termscp from PowerShell with a single command: + +```ps +irm https://termscp.rs/install.ps1 | iex +``` + +Alternatively, install it with [Chocolatey](https://chocolatey.org/): + +```ps +choco install termscp +``` + +## NetBSD + +Install termscp from the official repositories: + +```sh +pkgin install termscp +``` + +## Arch Linux + +Install termscp from the official repositories: + +```sh +pacman -S termscp +``` + +## Requirements + +The following system dependencies are required to run termscp. + +- Linux users: + - libdbus-1 + - pkg-config + - libsmbclient +- FreeBSD and NetBSD users: + - dbus + - pkgconf + - libsmbclient + +### Optional requirements + +These dependencies are not required to run termscp, but they are needed to +enjoy all of its features. + +- Linux and FreeBSD users, to open files via `V` (at least one of these): + - xdg-open + - gio + - gnome-open + - kde-open +- Linux users: a keyring manager. Read more in the + [Password security](../configuration/password-security.md) page. +- WSL users, to open files via `V`: + - [wslu](https://github.com/wslutilities/wslu) + +## Updating termscp + +To update termscp to the latest version, run it from the command line with: + +```sh +(sudo) termscp --update +``` + +For all platforms and methods, see . diff --git a/docs/en-US/index.md b/docs/en-US/index.md index b9e6eae..a4e0d6f 100644 --- a/docs/en-US/index.md +++ b/docs/en-US/index.md @@ -1,3 +1,28 @@ # termscp -Placeholder. +![termscp explorer](https://github.com/veeso/termscp/blob/main/assets/images/explorer.gif?raw=true) + +termscp is a feature-rich terminal file transfer client and explorer with a +TUI (Terminal User Interface). It lets you connect to a remote server to +upload and download files while interacting with your local file system at the +same time. termscp runs on Linux, macOS, FreeBSD, NetBSD, and Windows. + +## Features + +- Multiple transfer protocols: SFTP, SCP, FTP and FTPS, Kube, S3, SMB, + and WebDAV. +- Dual-pane explorer to browse and operate on both the remote and the local + file system: create, remove, rename, search, view, and edit files. +- Bookmarks and recent connections to quickly reconnect to your favorite + hosts. +- View and edit files with your favorite editor. +- SFTP/SCP authentication with SSH keys or username and password. +- Embedded terminal for running commands on your system. +- Make it yours: themes, custom file explorer format, customizable text + editor, and customizable file sorting. +- Desktop notifications when a large file has been transferred. +- File watcher that keeps your changes synchronized with the remote host. +- Save your passwords in your operating system's key vault. +- Rust-powered and built with an eye on performance. + +Ready to try it? See [Installation](getting-started/installation.md).