PowerShell DSC for Linux, Step by Step

PowerShell DSC for Linux, Step by Step

  • Comments 20
  • Likes

We are privileged to have a guest blogger on Building Clouds, Kristopher Bash.  Kris is a Senior Program Manager in the Microsoft Open Source Technology Center.  Last week at TechEd, Jeffrey Snover was a surprise guest in Don Jones’ presentation, where he demonstrated applying a configuration to a Linux box using PowerShell DSC through standards based management technology, WS-Man.

Kris has authored a step by step guide on the subject and we are lucky to have him share his work via BCB!


Building and Installing DSC for Linux

We have just announced the initial availability of a CTP for Windows PowerShell Desired State Configuration for Linux! This initial release is delivered as open-source code, and in this post, I will provide a detailed walkthrough for building and installing the DSC LCM on a Linux computer and applying your first configuration.


Building OMI 1.0.8 requires the following packages:

  • pam-devel
  • openssl-devel


In this walkthrough, I will build and install OMI and DSC on a CentOS 6 Linux computer.

·         Firstly, I will install the required prerequisite packages to build OMI and the DSC components:

root@lab-dev-02  # yum groupinstall 'Development Tools'

root@lab-dev-02  # yum install pam-devel

root@lab-dev-02  # yum install openssl-devel


·         Then, I can download and extract OMI 1.0.8 from The Open Group (https://collaboration.opengroup.org/omi/documents/30532/omi-1.0.8.tar.gz).  I’ll use /root/downloads as my working directory for OMI and DSC:

root@lab-dev-02  # mkdir /root/downloads

root@lab-dev-02  # cd /root/downloads

root@lab-dev-02  # wget https://collaboration.opengroup.org/omi/documents/30532/omi-1.0.8.tar.gz

root@lab-dev-02  # tar -xvf omi-1.0.8.tar.gz


·         Next, I’ll configure, build, and install OMI 1.0.8.  By default, this will install OMI to /opt/omi-1.0.8/

root@lab-dev-02  # cd omi-1.0.8/

root@lab-dev-02  # ./configure

created /root/downloads/omi-1.0.8/output

root@lab-dev-02  # make

root@lab-dev-02  # make install

Successfully installed under under: ///opt/omi-1.0.8


·         OMI 1.0.8 is now installed on my computer, and I can move on to installing the DSC components (Local Configuration Manager and Resource Providers).  I’ll install Python and download the DSC components:

root@lab-dev-02  # yum install python

root@lab-dev-02  # yum install python-devel

root@lab-dev-02  # cd /root/downloads

root@lab-dev-02  # wget https://github.com/MSFTOSSMgmt/WPSDSCLinux/releases/download/v1.0.0-CTP/PSDSCLinux.tar.gz

root@lab-dev-02  # tar -xvf PSDSCLinux.tar.gz
root@lab-dev-02  # mv ./dsc/* ./

root@lab-dev-02  # ls -l

total 7504

-r-xr-xr-x.  1 3482 3482      78 May 12 09:53 configure

drwxrwxr-x.  2 3482 3482    4096 May 12 09:53 Example DSCs

-rw-r--r--.  1 root root   11862 May 15 08:41 index.html

drwxrwxr-x.  5 3482 3482    4096 May 12 09:53 LCM

-r--r--r--.  1 3482 3482    9144 May 12 09:53 license.txt

-r--r--r--.  1 3482 3482     183 May 12 09:53 Makefile

drwxr-xr-x. 46 root root    4096 May 15 08:45 omi-1.0.8

-rw-r--r--.  1 root root 3623018 May 15 08:41 omi-1.0.8.tar.gz

drwxrwxr-x.  9 3482 3482    4096 May 12 09:57 Providers

-rw-r--r--.  1 root root 4003840 May 12 10:58 PSDSCLinux.tar

-r--r--r--.  1 3482 3482    3958 May 12 09:53 README.txt
root@lab-dev-02  # make

root@lab-dev-02  # make reg


Now, both OMI and the Desired State Configuration components (Local Configuration Manager and Resource Providers) are installed.

Running OMI and the LCM

·         The DSC installation performed in the previous steps registers the Local Configuration Manager as an OMI provider with OMI, so I simply need to run omiserver to enable DSC:

To run omiserver in an active tty (which is useful for debugging DSC):

root@lab-dev-02  # OMI_HOME=/opt/omi-1.0.8 /opt/omi-1.0.8/bin/omiserver


To run omiserver as a background process (daemon):

root@lab-dev-02  # OMI_HOME=/opt/omi-1.0.8 /opt/omi-1.0.8/bin/omiserver -d



·         For ongoing management of the Linux system, we clearly want omiserver to run as a service and start on boot of the Linux computer. For that, we’ll need to create an init script.   Here is an example init script:

#! /bin/sh


 # Provides:          omiserver

 # Required-Start:    $local_fs $remote_fs

 # Required-Stop:    $local_fs $remote_fs

 # Default-Start:     3 4 5

 # Default-Stop:      0 1 2 6

 # Short-Description: omiserver initscript

 # Description:      omiserver



 # Do NOT "set -e"



 export OMI_HOME=/opt/omi-1.0.8/







 # Define LSB log_* functions.

 # Depend on lsb-base (>= 3.0-6) to ensure that this file is present.

 . /lib/lsb/init-functions



 # Function that starts the daemon/service




         /opt/omi-1.0.8/bin/omiserver -d




 # Function that stops the daemon/service




       pid=`cat $PIDFILE`

        kill -9 $pid



 case "$1" in













         echo "Usage: $SCRIPTNAME {start|stop|restart}" >&2

         exit 3








·         To use this script, I copied it to the file:  /etc/init.d/omiserver and used chkconfig to register it as a service:

root@lab-dev-02  # chmod 755 /etc/init.d/omiserver

root@lab-dev-02  # chkconfig omiserver on

root@lab-dev-02  # service omiserver start


·         Some notes about OMI:

o   OMI configuration is controlled in the omiserver.conf file.  This file can be used to modify the HTTP/HTTPS ports and change the SSL certificate used for HTTPS/TLS.

o   The default ports are 5985/5986


Using DSC for Linux

If you are familiar with Desired State Configuration for Windows computers, you will quickly recognize how consistent the experience is for DSC for Linux.  In this section, I’ll walk through the basic use of DSC for Linux using the Linux VM we configured in the prior section.

Importing the PS Module

In order to convert our PS Configuration{} to a MOF file, we will need the Linux DSC Resource MOF files on the Windows computer.  We have provided a PowerShell module with these MOF files.  To install the PS module:

·         Get the nx-PSModule.zip file( https://github.com/MSFTOSSMgmt/WPSDSCLinux/releases/download/v1.0.0-CTP/nx-PSModule.zip) and extract it to: %SystemRoot%\system32\WindowsPowerShell\v1.0\Modules\

·         To import this in a Configuration{} block, simply include the line:
Import-DscResource -Module nx

Connecting to OMI

OMI and DSC for Linux, uses the standard WS-Management protocol for remote communication. So, for remote sessions, we will use a CIMSession object (created by New-CIMSession) as the value of a –CIMSession parameter in the DSC cmdlets. 
$cred=Get-Credential -UserName:"root" -Message:"Root User?"
$opt = New-CimSessionOption -UseSsl:$true -SkipCACheck:$true -SkipCNCheck:$true -SkipRevocationCheck:$true
$linuxcomp=New-CimSession -Credential:$cred -ComputerName:lab-dev-02 -Port:5986 -Authentication:basic -SessionOption:$opt


This CIMSession object can then be used in our subsequent Get/Set/Test-DSCConfiguration cmdlets:
PS C:\windows\system32> Get-DscConfiguration -CimSession:$linuxcomp
Get-DscConfiguration : Current configuration does not exist. Execute Start-DscConfiguration command with -Path parameter to specify a configuration file and create a current configuration first.

Create a Simple Configuration

A DSC Configuration{} for Linux is no different than one for Windows, other than the Resource class names and properties that are used in the configuration.  For example, here is a basic file configuration:

Configuration MyDSCDemo


   Import-DSCResource -Module nx

   Node "lab-dev-02"{    

        nxFile myTestFile


            Ensure = "Present" 

            Type = "File"

            DestinationPath = "/tmp/dsctest"   

            Contents="This is my DSC Test!"




Notice that Import-DSCResource was used to import the Linux resource provider definitions.  These resource providers have names that begin with the “nx” prefix, and currently include:

·         nxFile

·         nxUser

·         nxGroup

·         nxScript

·         nxService

To generate the configuration MOF, I can simply run MyDSCDemo after running the script with my Configuration{} block:
PS C:\windows\system32> MyDSCDemo -OutputPath:"C:\temp"
    Directory: C:\temp
Mode                LastWriteTime     Length Name                                                                                                                                                                
----                -------------     ------ ----                                                                                                                                                                
-a---         5/15/2014  10:28 AM       1150 lab-dev-02.mof                                                                                                                                                      

Apply the Configuration

The configuration MOF created in the previous step was written to C:\temp.  Now, combining the CIMSession and output MOF, I can use Start-DSCConfiguration to apply my configuration:
PS C:\windows\system32> Start-DscConfiguration -CimSession:$linuxcomp -Path:"C:\temp" -Verbose -Wait
VERBOSE: Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredSta
VERBOSE: Operation 'Invoke CimMethod' complete.
VERBOSE: Time taken for configuration job to complete is 0.186 seconds
After applying the configuration, I can see that my defined file is in the expected state:

root@lab-dev-02  # cat /tmp/dsctest

This is my DSC Test!


Testing it with Test-DSCConfiguration confirms that the state is as expected:

PS C:\windows\system32> Test-DscConfiguration -CimSession:$linuxcomp

Thank you and stay tuned to Building Clouds!

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • I see this is RHEL specific for using yum to add supporting bits to make this work. What's the story on the debian side and running this on Ubuntu??

  • What are the pros and cons of DSC on linux compared to guix or the nix package manager assuming that one never needs to target non-linux platforms?

  • This should be fun to play with!

  • The Snover RT from TW, something about flying monkeys. I would add when pigs fly. Air Bacon ! Yummy!
    It has happened, well he hinted forever that DSC was going to be for many platforms...

  • Please check your instructions on installing the DSC components on the Linux system. You are untaring the PSDSCLinux.tar.gz into the /root/downloads dir. This is creating a /dsc folder with a cut down listing of files from your screen shot. Also it is a bit vague what you're doing with that make reg command. I will submit an issue on github regarding this.

  • Would this work for Macs?

  • @Arty: you should be able to compile OMI and the DSC "Local Configuration Manager" for Mac. However, the "resource" providers are pretty-specific to Linux and would likely need a good bit of modification to work on a Mac.

  • Following the above instructions exactly on CentOS 6.5. It seems I'm missing a file. I get an error running 'make reg' as root: /root/downloads/omi-1.0.8/output/bin/omireg: cannot read provider library: /root/downloads/omi-1.0.8/output/lib/libdsccore.so

    Anyone else?

  • Whoops looks like the instructions have been modified to include a 'make' before 'make reg'

    Works now. Thanks!

  • @_organicit: Debian/Ubuntu are completely viable with this DSC release. The only difference should be the prerequisite packages. Using apt-get to install the following should allow you to build on Debian/Ubuntu:

  • @_organicit: a few errors in these steps have now been corrected, including moving the contents of /dsc/ up a level and a missing "make" step before "make reg." Thanks for pointing these out!

  • The command "tar -xvf PSDSCLinux.tar" should be "tar -xvf PSDSCLinux.tar.gz"

  • Thanks for the quick turn around Kris!!

  • @Ravikanth - good catch, the file name for the tar operation has been corrected.

  • I was trying to configure LCM on Linux to use pull server - is it supported yet, and if so - do you plan to blog about it soon? That would be very helpful. For me: I was able to configure node, Get-DscLocalConfigurationManager returns desired configuration (that points to my WebDownloadManager), but I can't see anything in OMI_home/var/log/dsc.log about connecting to my pull server nor updated configuration on Linux box (even though corresponding mof file/ checksum file are present on pull server).