Skip to main content

Asynchronous Python WinRM client

Project description

At Zenoss we are working on a project to improve the reliability, performance and features of native Windows monitoring. The core of this project is this Python library for asynchronously managing Windows using the WinRM and WinRS services. This library will then be used by Zenoss to do automatic discovery and monitoring the way Zenoss users are used to with some new possibilities.

Right now we’re trying to get as much real world experience using the library as possible to prove out the reliability and performance improvements we’re hoping to achieve. If you have access to Windows servers, you can help! It doesn’t even require a Zenoss Core installation as this tool stands alone right now.

To use kerberos connections, you will need to download and build the python kerberos module from https://github.com/zenoss/pykerberos.

See the zenoss-windows forum for updates to the project, and leave your feedback there.

http://community.zenoss.org/community/forums/zenoss-windows

Installation

Ubuntu Server 12.04.1 LTS (Python 2.7.3)

sudo apt-get update

sudo apt-get -y install gcc python-dev libkrb5-dev krb5-user python-setuptools
# if prompted for your kerberos realm, leave it blank and choose OK

sudo easy_install txwinrm

# if you want to use a Windows domain
sudo genkrb5conf <windows domain> <domain controller IP address>

# now you can run the txwinrm commands (winrm, winrs, typeperf, and wecutil)

Centos 6.3 x86_64 (Python 2.6.6)

# as root
yum -y install gcc python-devel krb5-devel krb5-workstation python-setuptools
easy_install txwinrm

# if you want to use a Windows domain
genkrb5conf <windows domain> <domain controller IP address>

# now you can run the txwinrm commands (winrm, winrs, typeperf, and wecutil) as a normal user

Zenoss Core or Resource Manager 4.2.x installed on CentOS 6 (Zenoss Python 2.7)

# as root
yum -y install gcc krb5-devel krb5-workstation

# as the zenoss user
easy_install txwinrm

# as root (if you want to use a Windows domain)
genkrb5conf <windows domain> <domain controller IP address>

# now you can run the txwinrm commands (winrm, winrs, typeperf, and wecutil) as the zenoss user

Current Feature Support

  • HTTP

  • Basic authentication

  • WQL queries

  • WinRS

  • typeperf

  • Subscribe to the Windows Event Log

  • Kerberos authentication (domain accounts)

  • Payload encryption (Kerberos connections)

Future Feature Support

  • HTTPS

  • NTLM authentication (local accounts)

Configuring the Target Windows Machines

You can enable the WinRM service on Windows Server 2003, 2008 and 2012. Run Command Prompt as Administrator and execute the following commands

winrm quickconfig
winrm s winrm/config/service @{AllowUnencrypted="true";MaxConcurrentOperationsPerUser="4294967295"}
winrm s winrm/config/service/auth @{Basic="true"}
winrm s winrm/config/winrs @{MaxShellsPerUser="2147483647"}

WQL Queries

You can pass a single host a query via the command line…

$ winrm -r host -u user -f "select * from Win32_NetworkAdapter"

Another option is to create an ini-style config file and hit multiple targets with multiple queries. Example config is at examples/config.ini

$ winrm -c path/to/config.ini

This will send WinRM enumerate requests to the hosts listed in config.ini. It will send a request for each WQL query listed in that file. The output will look like

<hostname> ==> <WQL query>
    <property-name> = <value>
    ...
    ---- (indicates start of next item)
    <property-name> = <value>
    ...
...

Here is an example…

cupertino ==> Select name,caption,pathName,serviceType,startMode,startName,state From Win32_Service
  Caption = Application Experience
  Name = AeLookupSvc
  PathName = C:\Windows\system32\svchost.exe -k netsvcs
  ServiceType = Share Process
  StartMode = Manual
  StartName = localSystem
  State = Stopped
  ----
  Caption = Application Layer Gateway Service
  Name = ALG
...

A summary of the number of failures if any and number of XML elements processed appears at the end. The summary and any errors are written to stderr, so redirect stdin to /dev/null if you want terse output.

$ winrm -c path/to/config.ini >/dev/null

Summary:
  Connected to 3 of 3 hosts
  Processed 13975 elements
  Failed to process 0 responses
  Peak virtual memory useage: 529060 kB

  Remote CPU utilization:
    campbell
      0.00% of CPU time used by WmiPrvSE process with pid 1544
      4.00% of CPU time used by WmiPrvSE#1 process with pid 1684
      4.00% of CPU time used by WmiPrvSE#2 process with pid 3048
    cupertino
      0.00% of CPU time used by WmiPrvSE process with pid 1608
      3.12% of CPU time used by WmiPrvSE#1 process with pid 1764
      9.38% of CPU time used by WmiPrvSE#2 process with pid 2608
    gilroy
      1.08% of CPU time used by WmiPrvSE process with pid 1428
      5.38% of CPU time used by WmiPrvSE#1 process with pid 1760
      4.30% of CPU time used by WmiPrvSE#2 process with pid 1268

The ‘-a’ option specifies the authentication method. Currently supported values are ‘basic’ and ‘kerberos’. ‘basic’ is the default.

The ‘-d’ option increases logging, printing out the XML for all requests and responses, along with the HTTP status code.

WinRS

The winrs program has four modes of operation:

  • interactive (default): Execute many commands in an interactive command prompt on the remote host

  • single: Execute a single command and return its output

  • long: Execute a single long-running command like ‘typeperf -si 1’ and check the output periodically

  • batch: Opens a command prompt on the remote system and executes a list of commands (actually right now it executes one command twice as a proof-of-concept)

An example of interactive mode

$ winrs interactive -u Administrator -x 'typeperf "\Memory\Pages/sec" "\PhysicalDisk(_Total)\Avg. Disk Queue Length" "\Processor(_Total)\% Processor Time" -si 1' -r oakland
Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. All rights reserved.
C:\Users\Default>dir
Volume in drive C has no label.
Volume Serial Number is 5E71-6BA3
Directory of C:\Users\Default
02/22/2013  03:42 AM    <DIR>          Contacts
02/22/2013  03:42 AM    <DIR>          Desktop
02/22/2013  03:42 AM    <DIR>          Documents
02/22/2013  03:42 AM    <DIR>          Downloads
02/22/2013  03:42 AM    <DIR>          Favorites
02/22/2013  03:42 AM    <DIR>          Links
02/22/2013  03:42 AM    <DIR>          Music
02/22/2013  03:42 AM    <DIR>          Pictures
02/22/2013  03:42 AM    <DIR>          Saved Games
02/22/2013  03:42 AM    <DIR>          Searches
02/22/2013  03:42 AM    <DIR>          Videos
0 File(s)              0 bytes
11 Dir(s)   7,905,038,336 bytes free

C:\Users\Default>exit

An example of single mode

$ winrs single -u Administrator -x 'typeperf "\Memory\Pages/sec" "\PhysicalDisk(_Total)\Avg. Disk Queue Length" "\Processor(_Total)\% Processor Time" -sc 1' -r oakland
{'exit_code': 0,
 'stderr': [],
 'stdout': ['"(PDH-CSV 4.0)","\\\\AMAZONA-SDFU7B1\\Memory\\Pages/sec","\\\\AMAZONA-SDFU7B1\\PhysicalDisk(_Total)\\Avg. Disk Queue Length","\\\\AMAZONA-SDFU7B1\\Processor(_Total)\\% Processor Time"',
            '"04/19/2013 21:43:48.823","0.000000","0.000000","0.005660"',
            'Exiting, please wait...',
            'The command completed successfully.']}

An example of long mode

$ winrs long -u Administrator -x 'typeperf "\Memory\Pages/sec" "\PhysicalDisk(_Total)\Avg. Disk Queue Length" "\Processor(_Total)\% Processor Time" -si 1' -r oakland
  "(PDH-CSV 4.0)","\\AMAZONA-SDFU7B1\Memory\Pages/sec","\\AMAZONA-SDFU7B1\PhysicalDisk(_Total)\Avg. Disk Queue Length","\\AMAZONA-SDFU7B1\Processor(_Total)\% Processor Time"
  "04/19/2013 21:43:10.603","0.000000","0.000000","18.462005"
  "04/19/2013 21:43:11.617","0.000000","0.000000","0.000464"
  "04/19/2013 21:43:12.631","0.000000","0.000000","1.538423"
  "04/19/2013 21:43:13.645","0.000000","0.000000","0.000197"

An example of batch

$ winrs batch -u Administrator -x 'typeperf "\Memory\Pages/sec" "\PhysicalDisk(_Total)\Avg. Disk Queue Length" "\Processor(_Total)\% Processor Time" -sc 1' -r oakland
Creating shell on oakland.

Sending to oakland:
  typeperf "\Memory\Pages/sec" "\PhysicalDisk(_Total)\Avg. Disk Queue Length" "\Processor(_Total)\% Processor Time" -sc 1

Received from oakland:
  "(PDH-CSV 4.0)","\\AMAZONA-SDFU7B1\Memory\Pages/sec","\\AMAZONA-SDFU7B1\PhysicalDisk(_Total)\Avg. Disk Queue Length","\\AMAZONA-SDFU7B1\Processor(_Total)\% Processor Time"
  "04/19/2013 21:43:39.198","0.000000","0.000000","0.000483"
  Exiting, please wait...
  The command completed successfully.

Sending to oakland:
  typeperf "\Memory\Pages/sec" "\PhysicalDisk(_Total)\Avg. Disk Queue Length" "\Processor(_Total)\% Processor Time" -sc 1

Received from oakland:
  "(PDH-CSV 4.0)","\\AMAZONA-SDFU7B1\Memory\Pages/sec","\\AMAZONA-SDFU7B1\PhysicalDisk(_Total)\Avg. Disk Queue Length","\\AMAZONA-SDFU7B1\Processor(_Total)\% Processor Time"
  "04/19/2013 21:43:41.054","0.000000","0.000000","0.000700"
  Exiting, please wait...
  The command completed successfully.

Deleted shell on oakland.

Exit code of shell on oakland: 0

Typeperf

txwinrm’s typeperf command allows you to run a remote typeperf command, check the output periodically, parse it, and print it to stdout. It support the -si option and multiple counters. Here is an example:

$ typeperf -r gilroy -u Administrator '\Processor(_Total)\% Processor Time' '\memory\Available Bytes' '\paging file(_Total)\% Usage'
\memory\Available Bytes
  00:54:27: 193130496.0
\paging file(_Total)\% Usage
  00:54:27: 0.012207
\Processor(_Total)\% Processor Time
  00:54:27: 0.004487
\memory\Available Bytes
  00:54:28: 193216512.0
  00:54:29: 193982464.0
\paging file(_Total)\% Usage
  00:54:28: 0.012207
  00:54:29: 0.012207
\Processor(_Total)\% Processor Time
  00:54:28: 1.542879
  00:54:29: 0.004487
\memory\Available Bytes
  00:54:30: 193933312.0
  00:54:31: 193941504.0
\paging file(_Total)\% Usage
  00:54:30: 0.012207

Subscribing to the Windows Event Log

The following command shows an example of subscribing to the Windows event log:

$ wecutil -r saratoga -u Administrator
Pull #1
Event(system=System(provider='Microsoft-Windows-EventForwarder', event_id=111, event_id_qualifiers=None, level=None, task=None, keywords=None, time_created=datetime.datetime(2013, 5, 8, 20, 29, 31, 132000), event_record_id=None, channel=None, computer='saratoga.solutions.loc', user_id=None), data=None, rendering_info=None)
Pull #2

You can run wecutil against a matrix of hosts and event queries by using a config file.

$ wecutil -c examples/config.ini
milpitas System/'*' pull #1 of 2
milpitas Application/'*' pull #1 of 2
gilroy System/'*' pull #1 of 2
...
milpitas System/'*' Event(system=System(provider='Microsoft-Windows-...
...
milpitas Application/'*' pull #2 of 2
...

Summary:
  Connected to 4 of 4 hosts
  Processed 12 events
  Peak virtual memory useage: 361060 kB

  Remote CPU utilization:
    saratoga
      0.15% of CPU time used by WmiPrvSE process with pid 1640
      0.96% of CPU time used by WmiPrvSE#1 process with pid 2000
      0.00% of CPU time used by WmiApSrv process with pid 604
      0.07% of CPU time used by WmiPrvSE#2 process with pid 1604
    gilroy
      0.00% of CPU time used by WmiPrvSE process with pid 1384
      0.00% of CPU time used by WmiPrvSE#1 process with pid 1684
      0.00% of CPU time used by WmiApSrv process with pid 1924
      0.15% of CPU time used by WmiPrvSE#2 process with pid 1348
    milpitas
      0.36% of CPU time used by wmiprvse process with pid 1924
      1.01% of CPU time used by wmiprvse process with pid 816
    berkeley
      0.00% of CPU time used by WmiPrvSE process with pid 1624
      0.00% of CPU time used by WmiPrvSE#1 process with pid 1744
      0.00% of CPU time used by WmiApSrv process with pid 1620
      0.07% of CPU time used by WmiPrvSE#2 process with pid 1280

Feedback

To provide feedback on txwinrm start a discussion on the zenoss-windows forum on community.zenoss.org: http://community.zenoss.org/community/forums/zenoss-windows

Zenoss uses JIRA to track bugs. Create an account and file a bug, or browse reported bugs: http://jira.zenoss.com/jira/secure/Dashboard.jspa

Unit Test Coverage

As of Apr 16, 2013…

$ txwinrm/test/cover
........................
----------------------------------------------------------------------
Ran 24 tests in 7.910s

OK
Name                Stmts   Miss  Cover
---------------------------------------
txwinrm/__init__        0      0   100%
txwinrm/constants      18      0   100%
txwinrm/enumerate     259     46    82%
txwinrm/shell         114     34    70%
txwinrm/util           89     24    73%
---------------------------------------
TOTAL                 480    104    78%

Develop

Run txwinrm/test/precommit before merging to master. This requires that you…

easy_install flake8
easy_install coverage
git clone https://github.com/dgladkov/cyclic_complexity

Project details


Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page