Migrating from 1.x

TL;DR

• The Apache CXF backend was removed; the dependency-free client is the only implementation.
• HTTPS now validates the certificate and verifies the hostname by default (1.x trusted every certificate). Self-signed hosts that used to work will now fail the TLS handshake until you trust the certificate or opt out.
• Kerberos over plain HTTP is rejected, even as a fallback: see Other behavior changes.
• File copy for localFileToCopyList now goes through the WinRM channel instead of SMB.
• A few CXF/SMB-only classes were removed.
• A new fluent API (WinRMClient) is the recommended way to use the library; the 1.x static helpers remain supported.

TLS is validated by default

The 1.x CXF client silently trusted every TLS certificate and skipped hostname verification. The 2.0.00 client uses the JDK's default validating socket factory instead, so HTTPS connections to hosts with self-signed or otherwise untrusted certificates now fail during the handshake.

To restore connectivity, either:

• install the server certificate (or its issuing CA) into a Java trust store — -Djavax.net.ssl.trustStore=... (recommended); or
• disable validation with -Dorg.metricshub.winrm.tls.insecure=true (insecure — testing only).

See TLS / HTTPS^[3] for details.

The CXF backend was removed

The dependency-free client is now the only implementation. There is no switch to fall back to the Apache CXF backend — if you still need it, stay on winrm-java 1.x.

File copy no longer uses SMB

Files listed in localFileToCopyList for WinRMCommandExecutor.execute(...)^[4] are no longer copied over SMB. They are transferred through the WinRM command shell (chunked base64, decoded on the host with certutil and verified with a digest). The consequences:

• No SMB requirement — TCP port 445 no longer needs to be reachable, no administrative or temporary share is created on the host, and the copy now works from any client OS (1.x wrote through a Windows UNC path and only worked from a Windows client).
• Files land in <windir>\Temp\winrm-upload-<CLIENT-COMPUTER-NAME> instead of 1.x's SEN_ShareFor_<CLIENT-COMPUTER-NAME>$. Where ACLs are hardened, grant write access on the new path. Directories left by 1.x are not reused and can be deleted (Where files land^[5]).
• The remote copy is content-addressed: a fragment of the content digest is inserted before the file extension (for example script.1a2b3c4d5e6f.vbs). Same-named files with different content can no longer overwrite each other, and a script that reads its own name (WScript.ScriptName) will see the digest fragment.
• A file already present on the host with an identical digest is not transferred again.
• The transport is meant for small script files, not bulk data.

Other behavior changes

• Kerberos requires HTTPS. On an HTTP endpoint, any authentication list that contains KERBEROS fails before connecting (Kerberos over WinRM requires HTTPS ...), even [NTLM, KERBEROS], which 1.x served with NTLM. Use HTTPS, or remove KERBEROS from lists used over HTTP (Authentication^[6]).
• Command output is decoded as UTF-8. The shell runs under console code page 65001 (1.x decoded the output with the host's ANSI code page), so non-ASCII characters now come through intact. WindowsRemoteProcessUtils.getWindowsEncodingCharset() is deprecated. See Character encoding^[7].
• Result collections are unmodifiable. WinRMWqlExecutor.getHeaders()/getRows() and WqlQuery.getSelectedProperties()/getSubPropertiesMap() return unmodifiable collections: copy them before modifying.

Fewer dependencies

Removing CXF and SMB leaves the library with zero runtime dependencies: the Apache CXF / JAX-WS / JAXB stack is gone, and so are smbj, BouncyCastle, SLF4J, mbassador, and asn-one. The library is a single jar of a few hundred kB, and it no longer references any logging API — problems are reported through exceptions^[8] only.

Removed types

These types and members were public in 1.x but are removed in 2.0.00. Code that referenced them will not compile against 2.0.00 (all were CXF- or SMB-specific):

• KerberosCredentialsException — was thrown only by CXF internals.
• SmbTempShare and WindowsRemoteProcessUtils.copyLocalFilesToShare(...) — replaced by the WinRM-channel file transfer. WindowsTempShare keeps its API, but the share it creates is now winrm-upload-<CLIENT-COMPUTER-NAME>: no trailing $, so it is no longer hidden. WindowsRemoteProcessUtils.buildNewOutputFileName() now starts names with winrm-, not SEN_.
• The Apache CXF-based WinRMService and its service.client internals (AuthenticationEnum stays), along with the generated WSDL/XSD resources.

The 1.x entry points — WinRMWqlExecutor, WinRMCommandExecutor, WinRMEndpoint, WindowsRemoteCommandResult, the enums, and the exception types — keep their signatures.

Moving to the fluent API

The 1.x static helpers open a connection, authenticate, run one operation, and tear everything down. The fluent WinRMClient^[1] authenticates once and runs any number of operations over the same connection — a large win for anything that polls a host — and replaces the 10-argument positional calls with builders. Migration is mechanical:

// 1.x style (still works)
WinRMWqlExecutor result = WinRMWqlExecutor.executeWql(
    HTTP, "server", null, "DOMAIN\\user", password,
    null, "SELECT Name, State FROM Win32_Service",
    30_000L, null, singletonList(NTLM));
List<String> headers = result.getHeaders();
List<List<String>> rows = result.getRows();

// Fluent
try (WinRMClient client = WinRMClient.builder("server")
        .credentials("DOMAIN\\user", password)
        .timeout(Duration.ofSeconds(30))
        .build()) {
    WqlResult result = client.wql("SELECT Name, State FROM Win32_Service").execute();
    List<String> columns = result.columns();
    for (WqlRow row : result) {
        row.string("Name");   // by name, case-insensitive — no more index arithmetic
    }
}

// 1.x style (still works)
WindowsRemoteCommandResult result = WinRMCommandExecutor.execute(
    "CSCRIPT c:\\collect.vbs", HTTPS, "server", null, "DOMAIN\\user", password,
    null, 30_000L, List.of("c:\\collect.vbs"), null, singletonList(NTLM));

// Fluent
try (WinRMClient client = WinRMClient.builder("server").https()
        .credentials("DOMAIN\\user", password)
        .timeout(Duration.ofSeconds(30))
        .build()) {
    CommandResult result = client.command("CSCRIPT c:\\collect.vbs")
        .upload(Path.of("c:\\collect.vbs"))
        .execute();
    result.stdout();
    result.exitCode();
}