Metadata-Version: 1.0
Name: txwinrm
Version: 0.9.1
Summary: Asynchronous Python WinRM client
Home-page: https://github.com/zenoss/txwinrm
Author: Zenoss
Author-email: bedwards@zenoss.com
License: /Users/bedwards/vc/txwinrm/LICENSE
Description: txwinrm: An Asynchronous Python WinRM client
        ============================================
        
        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.
        
        See the zenoss-windows forum for updates to the project, and leave your
        feedback there. 
        
        http://community.zenoss.org/community/forums/zenoss-windows
        
        
        Current Feature Support
        -----------------------
        
        -  HTTP
        -  Basic authentication
        -  WQL queries
        -  WinRS
        -  typeperf
        -  Subscribe to the Windows Event Log
        -  Kerberos authentication (domain accounts)
        
        
        Future Feature Support
        ----------------------
        
        -  HTTPS
        -  NTLM authentication (local accounts)
        
        
        Installation
        ------------
        
        Install this application into your Python site libraries with:
        
        ::
        
            $ python setup.py install
        
        
        Dependencies
        ------------
        
        -  Python 2.7
        -  Twisted 11.0 or later (utilizes HTTP connection pools with Twisted
           12.1 or later)
        
        
        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:
        
        -  --single-shot or -s: Execute a single command and return its output
        -  --long-running or -l: Execute a single long-running command like
           'typeperf -si 1' and check the output periodically
        -  --interactive or -i: Execute many commands in an interactive command
           prompt on the remote host
        -  --batch or -b: 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 single-shot
        
        ::
        
            $ 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-running
        
        ::
        
            $ 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 interactive
        
        ::
        
            $ 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 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
        
        
        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
        
Platform: UNKNOWN
