Sessions, host keys and credentials

A script needs three things before it can move a file: where to connect, proof that the server is the right one, and a way to log in that does not leave a password lying around. This page covers all three.

Opening a connection

Use open with either a stored site or a URL.

open webserver
open sftp://deploy@files.example.org/
open ftpes://alice@ftp.example.com:2121/incoming/

The URL schemes are sftp, scp, ftp, ftpes, dav, davs and s3. A stored site carries everything you set in the Site Manager, including advanced settings, so it is the shortest form. A URL makes the script independent of the configuration, which suits servers and containers that start from nothing.

You can keep several connections open and move between them with session.

Pinning the host key

On first contact with an SSH server, linscp has to decide whether the key the server presents is genuine. In the GUI you answer a prompt. A script cannot, so it fails unless the key is already known.

There are two ways to make it known:

• Accept it once in the GUI. The key is then stored in the shared configuration and both programs trust it.

• Pass it in the script. This works with any configuration, including /ini=nul:

  open sftp://deploy@files.example.org/ -hostkey="ssh-ed25519 255 Jh3k...Qw8"

To get the exact string, connect in the GUI and copy it from Tabs › Server/Protocol Information, or use Generate Session URL/Code, which writes the -hostkey switch for you. For FTPS and WebDAV over TLS, the matching switch is -certificate= with the certificate’s fingerprint.

Caution

-hostkey=* accepts any key. It removes the protection against a server being impersonated. Use it only against a test server you control.

Logging in without a password in the script

Choose the first option that fits:

1. An SSH key. Pass it with -privatekey=. linscp-cli reads keys in PuTTY’s .ppk format; convert an OpenSSH key once with linscp-cli /keygen ~/.ssh/id_ed25519 /output=/home/alice/.ssh/id_ed25519.ppk. Give the key no passphrase only if the account it opens is limited to this job.

2. An SSH agent. On Linux linscp asks the agent named by $SSH_AUTH_SOCK, so a key loaded into ssh-agent needs no switch.

3. A password from the environment. The script refers to a variable, and whatever starts the job sets it:

   open sftp://deploy@files.example.org/ -password=%DEPLOY_PASSWORD% -hostkey="..."

4. A password from a file. With the /passwordsfromfiles switch, every password-type value (-password, -passphrase and the like) is read as the path of a file holding the secret:

   linscp-cli /passwordsfromfiles /script=job.txt

   open sftp://deploy@files.example.org/ -password=/home/alice/.secrets/deploy -hostkey="..."

   Restrict the file with chmod 600.

Avoid putting the password inside a URL. It ends up in shell history and process listings, and characters such as @ or : must be percent-encoded.

Failing fast when a secret is missing

Add /nointeractiveinput to every unattended run. If a password or passphrase turns out to be needed after all, linscp-cli cancels the prompt and fails with exit code 1 instead of waiting for keyboard input.

Linux

DEPLOY_PASSWORD="$(cat /home/alice/.secrets/deploy)" \
  linscp-cli /nointeractiveinput /script=job.txt

Windows

set /p DEPLOY_PASSWORD=<C:\Users\alice\secrets\deploy.txt
"C:\Program Files\linscp\linscp-cli.exe" /nointeractiveinput /script=job.txt

Each switch is described on the linscp-cli switches page.