1. Openwsman User Guide
    1. Requirements
    2. CIMOM Requirements and Configuration
    3. Downalod Details
    4. Installation of Openwsman from Source
      1. Openwsman Source Repository
        1. Subversion Access
        2. Browse the Subversion Tree
      2. Installation
    5. Openwsman Installation using RPM Packages
      1. Openwsman Installation
    6. Configuration File Options
      1. Server
        1. Authentication and Password Files
        2. Authentication Plugins
      2. Client
      3. CIM Plugin
    7. Running the Openwsman Service
      1. CIMOM Back End
        1. Installation and Configuration
        2. Namespaces
    8. Using the command line client
    9. Vista WinRM over OpenWSMAN Setup
      1. WinRM Client Configuration
      2. WinRM Service Configuration
      3. WinRM over Openwsman Test
    10. CIM Binding in Openwsman
      1. Accounting for Different CIM Namespaces
      2. Enumeration
        1. Polymorphism

Openwsman User Guide

Requirements

Most of the requirement are part of any modern Linux distribution and can be installed using the package installer that comes with your favorite Linux distribution. We recommend using recent Linux distribution as the project uses some recent features in the libraries.

  • libxml2 -- Libxml2 is the XML C parser and toolkit developed for the Gnome project.
  • SBLIM SFCC -- Small Footprint CIM Client. You will need to checkout the source from SBLIM CVS and compile it before attempting to compile Openwsman.
  • other development packages like autoconf, automake etc.

CIMOM Requirements and Configuration

The current version of openwsman uses the sfcc (Small Foortprint CIM Client) to connect to any CIMOM running on the same host using cimxml. This is not optimal and comes with some overhead, however the intention of the project is to initially support all CIMOMs and there is no common protocol or client interface that can be used to talk to all available CIMOMs.

We have tested with two CIMOMs and all other CIMOMs with cimxml support should also work, the CIMOMs we have tested with are:

  • Openwbem -- OpenWBEM is an enterprise-grade open-source implementation of WBEM, written in C++, suitable for commercial and non-commercial applications. Openwbem is the default CIMOM in Novell products, especially SLES10.
  • SBLIM SFC Broker -- Small Footprint CIM Broker

Downalod Details

The source for openwsman can be downloaded from the project page at Sourceforge. RPMs are currently being build using the SUSE build service. Preliminary RPMs can be downloaded from the following location:

http://repos.opensuse.org/home:/nashif/

Installation of Openwsman from Source

Openwsman Source Repository

Openwsman uses Subversion for Code version control. The Openwsman repository is hosted at Sourceforge and provides read only access to everyone and read/write access to developers. You can either view the repository online on Sourceforge or using this site which keeps an uptodate mirror of the SourceForge? repository.

In order to access a Subversion repository, you must install a special piece of software called a Subversion client. Subversion clients are available for most any operating system.

Subversion Access

This project's Sourceforge.net Subversion repository can be checked out through SVN with the following instruction set: 

 svn co https://openwsman.svn.sourceforge.net/svnroot/openwsman openwsman

(Warning: This is a generic Subversion checkout command which will pull all modules, tags and/or branches of the project. Please refer to project home page for specific SVN instructions, or use "Browse Repository" link; in most cases, you will want to add '/trunk' to the HTTPS URL above to check out only trunk (main development line)).

Information about accessing this Subversion repository may be found in our document titled Subversion (Version Control for Source Code).

Browse the Subversion Tree

Though Subversion repositories are most commonly accessed using a special piece of software called a Subversion client, we also provide a web-based interface to view Subversion repositories. Browsing the Subversion tree gives you a great view into the current status of this project's code. You may also view the complete history of any file in the repository.

After checking out the project from Subversion run 

./autoconfiscate

in the Top directory and follow that by running 

./configure <options>.

If you download a packaged version (a compressed tar), then there is no need to run ./autoconfiscate and you will be able to run the configuration script directly.

Installation

After all packages are installed, compile the source and install (make and then make install).

To be able to put the configuration files under /etc/openwsman, run the configure script with the --sysconfdir option using the value /etc. If this option is not used, the default will be under PREFIX (/usr/local/etc ).

Openwsman Installation using RPM Packages

This section describes installation of openwsman and the needed CIM packages to provide a complete stack. In this document and other documents we use Openwbem as an example. Openwsman however supports all CIMOMs providing a cim-xml interface. Openwbem with the OMC packages (OMC Project) provide a complete set of providers to manage both hardware and software, thus they provide a good example for different usage models of the WS-Management protocol.

Openwsman Installation

Download the needed the RPMs for the distribution you are using. Currently we provide RPM packages for recent SUSE/Novell distributions in addition to FC4 and FC5.

The RPMs can be downloaded from the SuSE Build repository. The following RPM packages are needed:

  • openwsman
  • sblim-sfcc

Configuration File Options

Openwsman uses an ini style configuration file for all components (server, client and plugins). Currently, the following options are supported

Server

The example below shows a typical server configuration. 

[server]
port = 8889
#ssl_port = 8888
ssl_cert_file = /etc/openwsman/servercert.pem
ssl_key_file = /etc/openwsman/serverkey.pem
digest_password_file = /etc/openwsman/digest_auth.passwd
basic_password_file = /etc/openwsman/simple_auth.passwd

min_threads = 1
max_threads = 4

#use_digest is OBSOLETED, see below.

#
# Authentication backend for BASIC authentication. Default is to read a configuration file defined with 'basic_password_file'
#

#basic_authenticator = libwsman_pam_auth.so
#basic_authenticator_arg = openwsman

Authentication and Password Files

The password files for BASIC and DIGEST can be created with the htpasswd and htdigest utilities. Both utilities usually come with Apache packages on Linux distributions.

The realm for openwsman has to be OPENWSMAN. An example password file for DIGEST with one entry: 

wsman:OPENWSMAN:5a659df1ac36d2f4eb84092145532919

If both password files for basic and digest authentication are defined then both methods will be offered by the service. The client will automatically connect using the strongest authentication method.

Authentication Plugins

Authentication plug-ins support only Basic authentication. DIGEST authentication support is only available using a password file created with htdigest or similar utilities.

Plain Text Plugins

Is the default plug-in used in Openwsman and provides access to a password file generated with htpasswd or similar utilities.

PAM Plugin

To activate PAM authentication, enable the PAM authentication plug-in the configuration file and provide the name of the PAM service. The service configuration has to be provided as a file in the /etc/pam.d directory and can for example have the following contents:

/etc/pam.d/openwsman: 

#%PAM-1.0
auth       required     pam_unix2.so    nullok
auth       required     pam_nologin.so
account    required     pam_unix2.so
password   required     pam_pwcheck.so  nullok
password   required     pam_unix2.so    nullok use_first_pass use_authtok
session    required     pam_unix2.so    none

Client

[client]
port = 8889
agent = openwsman 0.3.2

CIM Plugin

Until recently, the namespace in the resource URI (the part of the url before the class name) was very flexible. You could request something like that:

http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem (valid) and http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/Linux_ComputerSystem (invalid)

and both would work.

Now this does not work anymore. For CIM base classes you should use the DMTF namespace, for others you can specify the namespace in the configuration file. Depending on your CIM providers there might be no CIM/WSMan namespace available, so you can make something up, the list of namespaces I have as an example: 

vendor_namespaces =
OpenWBEM=http://schema.openwbem.org/wbem/wscim/1/cim-schema/2,
Linux=http://sblim.sf.net/wbem/wscim/1/cim-schema/2,
OMC=http://schema.omc-project.org/wbem/wscim/1/cim-schema/2,
REEF=http:///reef.sblim.sf.net/wbem/wscim/1/cim-schema/2,
CWS=http:///cws.sblim.sf.net/wbem/wscim/1/cim-schema/2

So the above Linux_ComputerSystem resource URI should actually be: 

http://sblim.sf.net/wbem/wscim/1/cim-schema/2/Linux_ComputerSystem

[cim]
default_cim_namespace = root/cimv2

# The following are in part fake namespaces for some publicly available CIM implementations.
vendor_namespaces = OpenWBEM=http://schema.openwbem.org/wbem/wscim/1/cim-schema/2,Linux=http://sblim.sf.net/wbem/wscim/1/cim-schema/2,OMC=http://schema.omc-project.org/wbem/wscim/1/cim-schema/2

Running the Openwsman Service

The server can run as a daemon, which would require root access; But it can be run in the foreground with debugging messages printed to stdout as well. This is the help output when you run the daemon: 

# /usr/sbin/wsmand --help
Usage:
  wsmand [Option...] WS-Management Server

Help Options
  -?, --help

Application Options
  -n, --no-plugins                                Do not load any plugins
  -S, --ssl                                       Work through SSL port
  -d, --debug                                     Start daemon in foreground and turn on debugging
  -s, --syslog=0-6                                Set the verbosity of syslog output.
  -c, --config-file=<file>                        Alternate configuration file
  -p, --pid-file=<file>                           PID file

CIMOM Back End

Installation and Configuration

Openwsman relies on a CIMOM as the back end for providing system information. Openwsman currently uses the SBLIM CIM client library which connects to major CIMOMs supporting cimxml or connects using a local interface to the SFC Broker.

While there is an added communication overhead using this library, the main purpose of the intial release of Openwsman is to implement the WS-Management specification. Later, better integration with CIMOMs is planned.

To get started, install a CIMOM with cimxml support and make sure it does support HTTP. For the authentication, make sure you follow one of the scnarios:

  • Allow anonymous connections (usefull only for testing), this way you can use either BASIC or DIGEST with openwsman.
  • Enable PAM authentication if Openwsman is also configured it. This way, both Openwsman and the CIMOM will use PAM.
  • Use the same BASIC password file for both the CIMOM and Openwsman.

Once the CIMOM is up and running, make sure you can access the classes using a WBEM client (e.g. wbemcli from the SBLIM project or the python client from OMC). If the classes are accessible then you are ready to use openwsman with the CIMOM.

Namespaces

Because Openwsman can be used by multiple vendors, the configuration file provides a way to define the vendor specific namespaces and how they corrospond to the CIM classes provided in the CIMOM. See the section about the configuration file for more details.

Using the command line client

The command line utility uses the client interface of the openwsman library and supports all features accepted by service in addition to experiemntal feature currently not available in the Openwsman service (Fragment level transfer and Filtering).

To view all support options, run the client with the --help-all options: 

# /usr/bin/wsman --help-all
Usage:
  wsman [Option...] <action> <Resource Uri>

Help Options
  -?, --help
  --help-all                                      Show help options
  --help-enumeration                              Enumeration Options
  --help-tests                                    Test Cases
  --help-cim                                      CIM Options
  --help-flags                                    Request Flags

Enumeration
  -m, --max-elements=<max number of elements>     Max Elements Per Pull/Optimized Enumeration
  -o, --optimize                                  Optimize enumeration results
  -E, --estimate-count                            Return estimation of total items
  -M, --enum-mode=epr|objepr                      Enumeration Mode
  -U, --enum-context=<enum context>               Enumeration Context (For use with Pull and Release)

Tests
  -f, --from-file=<file name>                     Send request from file
  -R, --print-request                             print request on stdout
  -Q, --request                                   Only output reqest. Not send it.
  -S, --step                                      Do not perform multiple operations (do not pull data when enumerating)

CIM
  -N, --namespace=<namespace>                     CIM Namespace (default is root/cimv2)
  -B, --binding-enum-mode=none|include|exclude    CIM binding Enumeration Mode

Flags
  -x, --filter=<filter>                           Filter
  -D, --dialect=<dialect>                         Filter Dialect
  -t, --timeout=<time in sec>                     Operation timeout in seconds
  -e, --max-envelope-size=<size>                  maximal envelope size
  -F, --fragment=<fragment>                       Fragment (Supported Dialects: XPATH)

Application Options
  -d, --debug=1-6                                 Set the verbosity of debugging output.
  -c, --cafile=<filename>                         Certificate file
  -u, --username=<username>                       User name
  -g, --path=<path>                               Path
  -p, --password=<password>                       Password
  -h, --hostname=<hostname>                       Host name
  -P, --port=<port>                               Server Port
  -X, --proxy=<proxy>                             Proxy name
  -Y, --proxyauth=<proxyauth>                     Proxy user:pwd
  -y, --auth=<basic|digest>                       Authentication Method
  -a, --method=<custom method>                    Method (Works only with 'invoke')
  -k, --prop=<key=val>                            Properties with key value pairs (For 'put', 'invoke' and 'create')
  -C, --config-file=<file>                        Alternate configuration file
  -O, --out-file=<file>                           Write output to file
  -V, --noverifypeer                              Not to verify peer certificate

The client requires an action, a resource uri and additional options to connect and authenticate with the server. 

wsman [Option...] <action> <Resource Uri>

Note that the Identify request does not require any Resource Uri.

Vista WinRM over OpenWSMAN Setup

WinRM Client Configuration

  • Install Vista RC1 or higher.
  • Activate “Command Prompt” window with “Administrator privilege.”
  • Click through to Start/All Programs/Accessories
  • Right-click on Command Prompt
  • Click on Run as administrator
  • Press Continue button.
  • Run the following “winrm” commands in the command prompt window to change the default settings: 
    winrm set winrm/config/client/auth @{Basic="true"} 

    winrm set winrm/config/client  @{AllowUnencrypted="true"}

    winrm set winrm/config/client  @{TrustedHosts="192.168.1.100"}

Note: Replace the 192.168.1.100 with the host address of the server hosting the target OpenWSMAN service.

WinRM Service Configuration

  • Run the following “winrm” commands in the command prompt window to enable WinRM firewall exception: 
    winrm quickconfig
  • Additionaly, security needs to be untightened bu enabling Basic Authentication and enabling encypred communication (required for testing only): 
    winrm set winrm/config/service/auth @{Basic="true"} 

    winrm set winrm/config/service  @{AllowUnencrypted="true"}

WinRM over Openwsman Test

Verify the OpenWSMAN service is running on the target server. Run the following “winrm command” to test the connection: 

winrm enumerate http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem -username:wsman -password:secret -r:143.166.157.213:8889/wsman -auth:basic

Output should look something like: 

CIM_ComputerSystem
    Name = ZPB9K34
    CreationClassName = CIM_ComputerSystem
    NameFormat = 'other'
    Dedicated = null
    ResetCapability = 1
    PrimaryOwnerName = null
    PrimaryOwnerContact = null
    EnabledState = 2
    OtherEnabledState = null
    RequestedState = 2
    EnabledDefault = 2
    TimeOfLastStateChange = null
    InstallDate = null
    OperationalStatus = null
    Status = null
    HealthState = 25
    Caption = null
    Description
    ElementName = server1.domain.com

CIM Binding in Openwsman

Openwsman supports the CIM data model using a special plugin which handles a CIM classes in a generic way. The mapping of the CIM data into WS-Management resources happens on the fly using the CIM binding guidelines published by the DMTF.

Currently the following features are supported:

Accounting for Different CIM Namespaces

A special Selector is defined to indicate the CIM namespace of the resource or resources for which the message is intended. 

<wsman:Selector Name=”__cimnamespace”>xs:anyURI</wsman:Selector>

Using the command line client, the namespace can be set using the namespace option, for example: 

wsman enumerate  http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem --port 8889 --username  wsman -p secret    -h somehost.example.com --namespace smash/ipmi

Enumeration

Polymorphism

Client and server support all three polymorphism modes:

  • None
  • IncludeSubClassProperties
  • ExcludeSubClassProperties

The following examples show the client request with the corresponding responses for !CIM_ComputerSystem. The example shows three providers with CIM_ComputerSystem derivative classes. The vendor namespaces are just examples and are not official.