NAME

XAS::Lib::WS::RemoteShell - A class for the XAS environment

SYNOPSIS

 use XAS::Lib::WS::RemoteShell;

 my $wsman = XAS::Lib::WS::RemoteShell->new(
     -username => 'Administrator',
     -password => 'password',
     -url      => 'http://localhost:5985/wsman',
 );

 # this appears to be the sequence that winrs uses.

 if ($wsman->create()) {
     
     $wsman->command('dir');
     $wsman->receive();
     $wsman->signal();
     $wsman->delete();
  
 }

 printf("%s", $wsman->stdout);
 printf("exit code: %s\n", $wsman->exitcode);

DESCRIPTION

This package implements a client for the RemoteShell feature of WS-Manage. Getting the RemoteShell feature working under Windows is not easy. The reasons for these problems may be hidden in a Knowledge Base article on MSDN. These problems are mostly related to authentication and quirks of the winrm server.

On Windows 2013 R2 the "Windows Remote Management Server" needs to be configured as follows:

From a powershell console.

 ps> cd WSman:\localhost\
 ps> cd Client
 ps> set-item AllowUnencrypted $true
 ps> set-item TrustedHosts "*"
 ps> dir
 ps> cd ..\Service
 ps> set-item AllowUnencrypted $true
 ps> cd Auth
 ps> set-item Basic $true
 ps> dir
 ps> cd ..
 ps> dir
 ps> cd ..

Other versions of Windows are done similarly. This will allow connections from a none Windows box. These connections will be in clear text. This should not be used on the public internet.

This configuration will allow for an unencrypted HTTP connection with BASIC Authentication to a local user account, on the target box. You may wish to use the local Administrator account.

The usage of SSL for security will require additional configuration. Which is not documented well. By default, Windows doesn't listen on port 5986.

Using a Domain account requires kerberos authentication. I have not gotten this to work with RemoteShell. It may require additional configuration for that to work. But this configuration is not documented. Hence, the current usage. Once again, refer to that mythical Knowledge Base articule on MSDN.

The Linux version (OpenWSMAN v2.2.3) doesn't implement the RemoteShell feature.

METHODS

new

This class inherits from XAS::Lib::WS::Base and takes the same parameters. The parameters:

    -keep_alive
    -auth_method

Have been defaulted to approbriate values.

create

This method makes the initial connection to the server and creates a remote shell. It returns TRUE if it was successful.

command($command)

This method will send a command to the server to be executed by the shell.

$command

The command string to send.

send

This method will send a buffer to the remote shell.

receive

This method will receive output from the remote shell. This will include output for STDOUT and STDERR. The exit code will also be retrieved from the command.

signal

This method will send a "terminate" signal to the remote shell.

delete

This method will delete the remote shell.

stdout

This method returns the output from STDOUT.

stderr

This method returns the output from STDERR.

exitcode

This method returns the exit code.

check_exitcode

This method will check the exit code. If the code is greater then 0 it will try to parse the stderr stream looking for a reason. This method throws an exception with the exit code and the parsed stderr.

SEE ALSO

XAS::Lib::WS::Base
XAS

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (c) 2012-2016 Kevin L. Esteb

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license at http://www.perlfoundation.org/artistic_license_2_0.