File Transfers

Uploading a file

Transfer-and-run — copy script files and rewrite the command to reference the remote copies (this is what upload(...) on the fluent command builder and localFileToCopyList in the legacy WinRMCommandExecutor.execute(...)^[1] do):

client.command("CSCRIPT c:\\scripts\\collect.vbs")
      .upload(Path.of("c:\\scripts\\collect.vbs"))
      .execute();

Explicit destination — copy one file to a path you choose (WinRMClient.uploadFile(...)^[2], or ShellFileCopy.copyLocalFileToRemoteFile(...)^[3] with a legacy executor):

client.uploadFile(Path.of("collect.ps1"), "C:\\Windows\\Temp\\collect.ps1");

Both use the same transfer engine described below; transfer-and-run adds the per-client transfer directory (with its housekeeping) and the command-line rewriting.

Where files land

With transfer-and-run, files are copied to a per-client-machine transfer directory on the remote host:

<windir>\Temp\winrm-upload-<CLIENT-COMPUTER-NAME>

• <windir> is discovered on the remote host with the WQL query SELECT WindowsDirectory FROM Win32_OperatingSystem — typically C:\Windows.
• <CLIENT-COMPUTER-NAME> is the name of the machine running the client (the COMPUTERNAME environment variable, or the local host name), which usually gives each client machine its own directory. Clients that report the same computer name (cloned machines, containers) share one directory, safely: the content-addressed names below keep their payloads apart. Versions before 2.0.00 used <windir>\Temp\SEN_ShareFor_<CLIENT-COMPUTER-NAME>$, exposed as a hidden SMB share — no share is created anymore, and a directory left behind by an older version is neither reused nor cleaned up: it can simply be deleted.
• The directory is created if missing (IF NOT EXIST ... MKDIR ...).

Inside that directory the remote file name is content-addressed: a 12-hex-digit fragment of the file's SHA-256 digest is inserted before the extension:

collect.vbs  →  <windir>\Temp\winrm-upload-MYHOST\collect.1a2b3c4d5e6f.vbs

Because the name identifies the content, two files with the same name but different content get different remote paths — concurrent clients (even ones whose computer names collide) can never overwrite each other's payload between verification and execution. The flip side: a script that inspects its own file name (e.g. WScript.ScriptName) sees the digest fragment.

Overlong names are truncated (on Unicode code-point boundaries) so that the complete remote path — including the temporary-file suffixes described below — stays within the traditional Windows MAX_PATH limit (260 characters) that old hosts still enforce; the digest fragment keeps truncated names unique.

With an explicit destination (uploadFile), the file lands exactly at the path you give — no content-addressing, no renaming. The destination must be an absolute Windows path, either drive-rooted (C:\...) or UNC (\\server\share\...), of at most 229 characters (room for the temporary-file suffixes within MAX_PATH); relative and drive-relative (C:x.ps1) paths are rejected, because they would resolve against the remote shell's current directory. The destination directory is created if missing. A UNC destination is a second hop from the host: without Kerberos credential delegation^[4] it typically fails with access denied.

How the bytes travel

The transfer rides the already-authenticated (and, over HTTPS or with NTLM, encrypted) WinRM command shell — every step below is an ordinary remote command:

1. Skip check. The destination is hashed on the host (certutil -hashfile <dest> SHA256, with a SHA1 fallback for pre-2012 hosts in the same command). If it already carries the digest of the local file, the upload is skipped entirely — re-running an identical script costs only the fixed bookkeeping (the directory-discovery query, the cleanup/MKDIR leg, and this digest probe), never the upload legs. A destination present with a different digest (e.g. corrupted in place) is remembered and repaired by replacement in step 4.

2. Upload. The file content is base64-encoded locally (76-character lines) and appended to a remote base64 sidecar file with chunked echo commands, batched into as few command legs as possible, each under cmd.exe's command-line length limit (~8 kB per leg).

3. Decode and verify. One command leg decodes the sidecar with certutil -f -decode into the staging file, deletes the sidecar, and hashes the staging file — the digest is compared against the locally computed one before going any further.

4. Publish and verify again. The verified staging file is moved onto the destination:

   • if the destination did not exist, MOVE — and if a concurrent transfer of the same content won the race, the staging copy is simply discarded (a destination that already carries the right digest is never rewritten, so a copy verified by another operation cannot be invalidated);
   • if the destination pre-existed with a mismatched digest, MOVE /Y force-replaces it (repair).

   The same command leg hashes the destination one last time: the operation only succeeds if the destination provably contains the local bytes. A failure during a repair can leave the destination replaced but unverified: the failure is reported, and the next transfer detects the mismatch and repairs it.

An empty local file skips steps 2–4: the destination is created with TYPE NUL and verified the same way.

<destination>.<unique>.part        the staging file (decoded content, verified before publish)
<destination>.<unique>.part.b64    the base64 sidecar consumed by certutil -decode

Command-line substitution

With transfer-and-run, after the files are copied, every occurrence of each local path in the command string is replaced — literally and case-insensitively — by the corresponding remote path, and the result is executed through CMD.EXE /C (...):

given:    CSCRIPT c:\scripts\collect.vbs /debug
uploads:  c:\scripts\collect.vbs
executes: CMD.EXE /C (CSCRIPT C:\Windows\Temp\winrm-upload-MYHOST\collect.1a2b3c4d5e6f.vbs /debug)

Notes:

• The match is a literal, case-insensitive substring match on the path as you passed it to upload(...) (its toString(): on a Windows client scripts/x.vbs becomes scripts\x.vbs) or localFileToCopyList — use the same spelling in the command (C:\Scripts\X.vbs and c:\scripts\x.vbs both match, but C:\SCRIPTS\..\SCRIPTS\X.VBS does not).
• A listed file that the command never references is still uploaded; the command is unchanged.
• Because the transfer legs run first, they are what creates the remote shell — so a workingDirectory(...) on the same request does not apply (the shell already exists, with its default directory, when the actual command runs).

Upload constraints and safety checks

• File names must be safely embeddable in a quoted cmd.exe argument and creatable on Windows. Rejected: names containing % or ! (cmd.exe expands them even between quotes), control characters, the Windows-forbidden characters < > : " / \ | ? *, names ending with a dot or a space, and reserved device names (CON, NUL, COM1…, with or without extension).
• Size: the mechanism is designed for small script files. Base64 over SOAP costs one WinRM operation per ~8 kB leg — fine for scripts, wrong for bulk data. The transfer runs under the command's timeout(...) with upload(...), and under the client's timeout with uploadFile(...) (no per-call override).
• Server operation quotas: old hosts cap concurrent WinRM operations per user very low (15 on Windows Server 2008 R2). Transfer steps are batched to minimize operations, and a command rejected by the quota before it could run is retried with escalating delays (5/10/15/20 s).
• Integrity: every path through the transfer ends with a digest verification of the actual destination; the digest is a transfer-integrity check (the channel itself is authenticated and, over HTTPS or with NTLM, encrypted).
• Host requirements: the account must be able to run remote commands and to write to the destination directory, and the host must provide certutil (transfer) and forfiles (housekeeping); transfer-and-run also needs WMI access, for its WQL query. See Preparing the Windows Host^[5].

Downloading a file

WinRMClient.downloadFile(...)^[2] copies a remote file to a local one — the counterpart of uploadFile(...), with the same guarantees: the content is verified, an identical copy is not transferred again, and a failure never leaves a truncated file behind. The same terminal exists on client.file(path)^[6], where the timeout can be set:

client.downloadFile("C:\\Windows\\Temp\\collect.log", Path.of("collect.log"));

long bytes = client.file("D:\\exports\\big.csv")
    .timeout(Duration.ofMinutes(10))
    .downloadTo(Path.of("big.csv"));   // bytes transferred, 0 when the local copy was already identical

When the local path is an existing directory, the file is written into it under its remote name, like cp: downloadFile("C:\\Windows\\Temp\\collect.log", Path.of("logs")) writes logs/collect.log. A remote name with a colon — an alternate data stream (a.txt:meta) or a drive-relative path (C:a.txt) — is refused there: name the local file explicitly. The destination's directory is created when needed.

Download of D:\exports\big.csv from server01 timed out after PT30S, 41943040 of 104857600 bytes
transferred: raise the timeout for large files

See also

• Remote Files^[7] — reading remote files (whole, byte ranges, streams) and listing directories through the WinRM channel
• Remote Commands^[11] — the command builder that carries the transfer
• Preparing the Windows Host^[5] — the privileges a transfer needs