Tclwinrm v1.0.3 

------------------------------------------
Description 
------------------------------------------

Tclwinrm is an opensource tcl interface to the Microsoft Windows Remote Management protocol
using remote shell. Typical uses for Tclwinrm:

	- manage Windows Servers from Linux
	- running Windows / DOS commands on Windows Servers
	- running Powershell scripts remotely
	- configuring or installing software
	- starting or stopping Windows services
	- custom application monitoring
	- general administration or automation
	- and so on ...

For more information on Winrm and Remote Shell:

http://msdn.microsoft.com/en-us/library/aa384426%28v=vs.85%29.aspx

A Google search will provide various blog postings on setting up
winrm on Windows Servers. 

Here is a link on setting it up on Windows Server Core 2008 R2:

http://www.cloudsidekick.com/blog/files/blog3.html


------------------------------------------
Repository and Download
------------------------------------------

https://github.com/cloudsidekick/tclwinrm

------------------------------------------
Bug and Feature Requests
------------------------------------------

https://github.com/cloudsidekick/tclwinrm/issues

------------------------------------------
How does it work? 
------------------------------------------

The Tclwinrm extension uses the Microsoft Winrm protocol to establish an remote shell on 
the targeted Windows server and passes a script or command to the remote shell. The connection is
asynchronous, therefore the remote shell is established and terminated each call. 

Tclwinrm uses http to connect to the Winrm port (default 5985), passing in credentials and the 
remote shell command. The output from the command is returned back to the caller. 

NOTE: currently only Basic Authentication is supported. Also make sure AllowUnencrypted is set to true.

Quick notes on setting up the winrm service on Windows Server 2008:

winrm qc -q
winrm set winrm/config/service/auth @{Basic="true"}
winrm set winrm/config/service @{AllowUnencrypted=True}

NOTE: TclCurl and TclOO are no longer required in Tclwinrm version 1.0.2. In removing the object oriented commands, the Tclwinrm commands have changed slightly. Therefore and scripts written for pre-1.0.2 will need to be modified.

------------------------------------------
Installation
------------------------------------------

Requirements - tcl 8.5, Tcllib and Tdom

Download the Tclwinrm tarfile Githum. Unzip the contents into  lib/tclwinrm directory in your tcl home directory. 
Make sure you have Tcllib, Tdom installed too. 

------------------------------------------
Usage
------------------------------------------

To create a new connection object to the Microsoft Winrm service:

tclwinrm::configure <protocol> <address> <port> <user> <password>

	protocol	- http or https (NOTE: https has not been tested)
	address		- FQDN or ip address of Windows Server to connect to
	port		- port, on 2008 R2 this should be 5985 for http, before R2 it was 80
	user		- user id with Winrs privleges, escape domain account with \
	password	- password for user id	

Example:

tclwinrm::configure http 10.242.210.49 5985 administrator adminpass]


To send a request to the remote shell:

tclwinrm::rshell <script> <timeout> <debug>

	script		- Any DOS or Powerscript script
	timeout		- Timeout length for command
	debug		- 0 or 1, turns verbose output off and on

------------------------------------------
TODO
------------------------------------------

	- test https, encrypted traffic
	- support more authentication methods besides Basic
	- bulletproof error handling

------------------------------------------
Samples
------------------------------------------

NOTE: these samples where tested on Windows Server 2008 and 2008 R2
using port 5985. They were run from a linux machine.

---------------------------------------------

The following sample will do a simple directory listing. 

package require tclwinrm
tclwinrm::configure http 10.242.210.49 5985 administrator adminpass
set command {dir c:\ }
set output [tclwinrm::rshell $command 120 1]
puts $output 

 Volume in drive C has no label.
 Volume Serial Number is D8D3-E1BF

 Directory of c:\

02/23/2011  08:42 PM    <DIR>          apps
12/06/2009  04:30 AM    <DIR>          inetpub
01/19/2008  11:11 AM    <DIR>          PerfLogs
02/17/2011  10:06 PM    <DIR>          Program Files
12/06/2009  04:38 AM    <DIR>          Program Files (x86)
02/17/2011  09:36 PM    <DIR>          Users
02/17/2011  09:23 PM    <DIR>          Windows
               0 File(s)              0 bytes
               7 Dir(s)   9,929,146,368 bytes free


---------------------------------------------

The following sample will execute a simple Powershell script. 

NOTE: Powershell scripts should be Base64 encrypted, see the following:

package require base64
package require tclwinrm
tclwinrm::configure http 10.242.210.49 5985 administrator adminpass

set script {$strComputer = $Host
Clear

$RAM = WmiObject Win32_ComputerSystem
$MB = 1048576

"Installed Memory: " + [int]($RAM.TotalPhysicalMemory /$MB) + " MB"}

set command "powershell -encodedcommand [::base64::encode -wrapchar "" [encoding convertto unicode $script]]"
set output [tclwinrm::rshell $command 120 1]
puts $output

Installed Memory: 614 MB