Skip to content

v3.1.00

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Oct 19:04
· 19 commits to main since this release
v3.1.00
876e058

Version 3.1.00 is a maintenance release for long-lived clients. A client that runs commands
indefinitely no longer exhausts the host's WSMan operation quota. A streaming read resumed after
a long pause no longer times out. WQL no longer drops rows whose selected properties are all empty.

Highlights

A long-lived client no longer exhausts the host's operation quota (#196)

Every command run in a shell holds one of the user's WSMan operations until the shell is deleted,
even after it completed. Until now, the client reused one shell forever. A client polling
indefinitely ended up with every command refused with WSManFault 2150859174 (the maximum number
of concurrent operations for this user has been exceeded), and it never recovered until it was
recreated. That happened after 15 commands on Windows Server 2008 R2 and after 1500 on later
versions. While the quota was full, the user's other connections were refused too, WQL included.

The client now replaces its shell (Delete, then Create, about 100 ms):

  • every 10 commands. The new WinRMClient.Builder.maxCommandsPerShell(int) changes that number.
    Use 1 to run each command in a shell of its own, like winrs;
  • when a command could not be terminated cleanly (its terminate Signal failed or was skipped);
  • on Windows Server 2008 R2, when the quota refuses a command in a shell that already ran
    commands. The command ran nothing, so it is retried once in a new shell. Later versions send
    this fault without its WSManFault code, so nothing reliable identifies it there.
WinRMClient client = WinRMClient.builder("server.example.net")
    .credentials("DOMAIN\\user", password)
    .maxCommandsPerShell(5)   // default: 10
    .build();

See Shell reuse.

Behavior changes

  • The remote shell no longer lives as long as the client (#196). The new shell gets the same
    working directory, environment variables and profile. But deleting the old shell ends any process
    a previous command left running in it, as close() always did. A process that must outlive its
    command belongs outside the shell, e.g. in a scheduled task.
  • A reaped shell, and the operation quota on Windows Server 2008 R2, are retried once in a new
    shell     whatever the retry policy. The other WSMan faults are still never retried. See
    Timeouts and errors.

Fixed

  • A streaming read resumed after a long pause no longer times out spuriously (#198). This
    happened when a consumer, e.g. a RemoteProcess read slowly, paused longer than the inactivity
    timeout and the host dropped the idle connection meanwhile. The reconnection inherited the
    expired deadline of the previous request. Its TCP connect and TLS handshake then got a 1 ms
    budget and failed with No response from the WinRM service. Each reconnection now gets a full
    inactivity timeout of its own — #200
  • A WQL row is no longer dropped when none of its selected properties came back (#201). WinRM
    leaves an empty or NULL array out of the response. So SELECT IPSecPermitTCPPorts FROM Win32_NetworkAdapterConfiguration returned no rows at all, where WMI returns one per adapter.
    Each instance is now a row, and string() returns null for the missing property —
    #204
  • WqlResult.columns() reads the property names of every row, not just the first one (#201).
    With SELECT * FROM Win32_NetworkAdapterConfiguration, a first adapter without IP configuration
    hid IPAddress, DefaultIPGateway, ... from the columns of all the rows —
    #204

Documentation

  • How WQL arrays are rendered. Elements are joined with | and there is no trailing separator.
    A one-element array reads like a scalar. An empty or NULL array is left out of the response.
    See Reading the result —
    #204
  • Pre-release review: CHANGELOG sections, the workingDirectory option and the retry rules
    updated for shell replacement — #205

Build

  • metricshub/workflows v6 → v8, required to deploy to Maven Central with Maven 3.10 —
    #203

Pull requests

  • Retire the shell when a command's terminate Signal does not go through (#196) — #197
  • Streaming command fails with a spurious timeout when reconnecting after an idle pause (#198) — #200
  • WQL arrays: document the rendering, keep rows whose properties are all empty (#201) — #204
  • Update metricshub/workflows to v8 — #203
  • Prepare the docs for 3.1.00 — #205

Full Changelog: v3.0.00...v3.1.00

Assets 7
Loading