This whitepaper outlines how you can use the web service interface to remotely schedule any Deployment Server job on any managed machine to run immediately.

Contents

• Overview
• Installation & Setup
  • Pre-requisites
  • .MSI Based Installation
• Using the Altiris Deployment Server Web Service
  • Option 1: View & Invoke the ScheduleNow method from a browser
  • Option 2: Call Web Service directly from URL
  • Detailed Description of Web Service URL
  • Securing the Web Service
• Example Use Case: Launch Deployment Server Jobs from Altiris Monitor Solution Alerts
  • Prepare Recovery Jobs in Deployment Server
    • Step 1: Create a recovery image of each blade
    • Step 2: Create a Unique Deploy Disk Image Job for each blade
  • Configure Monitor Solution to Launch the Recovery Job
    • Option 1: Launch Recovery Job Automatically from the Monitor Agent
    • Option 2: Launch Recovery Job automatically from Helpdesk
  • Configuring the Automation Rule in the Altiris Helpdesk
    • Step 1: Configure the Helpdesk Automation Rule
• Conclusion
• Appendix A – Manual Installation
• Appendix B – Web Service Source

Overview

Altiris Deployment Server provides comprehensive management features from either a Windows Console (Win32) or Web Console (DSWeb Console). However, users occasionally need to access Deployment Server features outside of these consoles (i.e. via scripts from other Altiris solutions or 3rd party tools). For these applications, Altiris provides a utility which allows administrators to schedule Deployment Server jobs and computers from the command line. The utility, named axsched.exe, is located in Deployment Server's eXpress share (%program files%\Altiris\eXpress\Deployment Server\). For this tool's syntax usage, consult the Altiris Deployment Servers User Guide.

The aexsched.exe utility works well when executed from the Deployment Server. It can be difficult to leverage for those applications where the utility must be called from a remote machine (due to the resulting need to create shares, configure access permissions, etc.). This paper provides an example of a web services interface for working with Deployment Server jobs and computers.

The web service interface (outlined in this whitepaper) provides the benefit of remotely scheduling any Deployment Server job on any managed machine to run immediately. By using this web service you can run jobs from scripts located on other machines, from separate management Consoles such as Dell OpenManage ITA, or through the Altiris Helpdesk Automation Rules (see Appendix B).

Note: While this functionality is currently planned to be included in releases of Altiris Deployment Server, it is important to note that it is not currently an officially recognized feature of the product. The files provided with this white paper are provided "as is" to allow for early adoption where it is needed and to collect customer feedback regarding the feature's implementation.

Installation & Setup

This section covers the pre-requisites and setting up the Altiris Deployment Server web service. The setup of the web service can be done with the Deployment Server web service .MSI or by manually copying the 4 required files and configuring the virtual directory. This section will cover how to setup the web service via .MSI. (See Appendix A for manual setup instructions)

Pre-requisites

The following is required:

• Deployment Server 6.5 or later Installed
• Microsoft Internet Explorer 6.0 or later
• Microsoft Internet Information Services (IIS)

.MSI Based Installation

Step 1: Create a recovery image of each blade

1. Download and extract the .msi based installation file:
   DS_RunNow_WebService.zip
2. From the Deployment Server machine running IIS, launch the DS_RunNow_WebService.msi
3. Accept the default through the wizard to complete the installation

Step 2: Verifying Your Installation

1. Open Internet Service Manager (Start –> Run –> inetmgr).
2. Select the dsjob virtual directory
3. In the right pane, right-click on dsjob_fromurl.asmx –> Browse

Internet Explorer will open to the web service url. Listed will be the available functions from the web service. (See Image)

Click to view.

Using the Altiris Deployment Server Web Service

Web service methods can be called in several ways. In this section we will outline two different options that can be used to schedule or run a deployment server job on a computer.

Option 1: View & Invoke the ScheduleNow method from a browser.

1. Open Internet Explorer, type the following URL and click Go:

http://<deploymentservername>/dsjob/dsjob_fromurl.asmx



Click to view.

2. Click the ScheduleNow method.
3. Provide a managed computer name and deployment server job name in the available fields.
4. Click Invoke to run the schedule the specified job on the specified computer.


Click to view.

Option 2: Call Web Service directly from URL

1. Open Internet Explorer
2. Type the following URL into the address bar, changing PE2850_1 & BackupServer_Job to a valid computer and job in your deployment console.

http://dsservername/dsjob/dsjob_fromurl.asmx/ScheduleNow?ComputerName=PE2850_1&JobName=BackupServer_Job

Click to view.

Securing the Web Service

The example in this whitepaper provides one method that can be used to schedule a job immediately through a web service. The web service can be invoked in a variety of ways (i.e. a script, 3rd party application, or by simply entering the URL and correct parameters into a web browser). While these methods of invocation may be suitable for some environments, it is not secure, and is not suitable for all environments.

The Altiris Helpdesk Solution provides functionality to securely invoke a URL based on criteria of any incident which is created, via Helpdesk's Automation Rules. This will be covered in the next section.

In addition to the Altiris Helpdesk solution, there are a variety of methods to secure web services, such as SSL and Client Certificates, SOAP encryption, or use of windows authentication. These methods go beyond the scope of this paper, however the references below are provided to assist in securing web services.

Securing Your ASP.NET Application and Web Services

Web Services Security in The .NET Framework

Example Use Case: Launch Deployment Server Jobs from Altiris Monitor Solution Alerts

So now that you have enabled Altiris Deployment Server to execute jobs via a web service call, what can you do with it? Out-of-te-box, Altiris Monitor Solution allows you to monitor thousands of metrics/processes/event IDs simply by enabling either the "Basic" or "Detailed" monitor packs. These monitor packs include a variety of categories that range from monitoring the Disk Read/Write I/O on your Windows servers to the Apache Server logs on your Linux machines. When using the Dell Monitor Pack, you can monitor any metric published by Dell OpenManage Server Administrator including Global Temperature, ESM Logs, Power Supplies, Cooling Fan Unit Status, etc.

Using Altiris Deployment Server in conjunction with Altiris Monitor Solution can give you the powerful ability to proactively manage your environment. For example, you can use Altiris Monitor Solution to detect hardware or software alerts and then automatically respond to them by executing Altiris Deployment Server functions.

Although this example uses the Altiris Monitor Solution, any other Altiris solution can use the DS web service. This section will focus on how to configure Altiris Monitor Solution to call a Deployment Server job to proactively take control of your environment.

Prepare Recovery Jobs in Deployment Server

In this example, the Altiris Monitor Solution for Dell Servers is used to monitors Dell PowerEdge 1855 blade servers. If Monitor Solution detects a failure on any of the production blades, it will automatically provision a spare blade with the image of the failing blade.

Note: If the spare blade is powered off, then you must ensure that Wake On LAN is enabled in the BIOS. If the NIC does not support WOL, the spare must be powered on and running the Altiris AClient Agent in order to receive the appropriate job.

Step 1: Create a recovery image of each blade

1. Use Altiris Deployment Server to create an image of each production blade that you want to be able to recover. Details on how to perform this task can be found in the Creating a Disk Image section of the Deployment Server Users Guide.

Step 2: Create a Unique Deploy Disk Image Job for each blade

1. For each blade you want to recover, provide a unique name to the Deploy Disk Image job that corresponds to each blade. For example, if 4 blades exist named: BLADE_1, BLADE_2, BLADE_3, BLADE_4:
   

   Click to view.

   Then name the 4 image deployment jobs, D_Blade_1_Image, D_Blade_2_Image, D_Blade_3_Image, D_Blade_4_Image.



Click to view.

Note: If BLADE_3 fails, then the D_Blade_3_Image job will be automatically scheduled to run on the spare blade sitting in reserve.

Step 3: Create a computer record for the spare blade

1. Open the Deployment Server Console.
2. In the Computer's Pane, right-click All Computers –> New Computer
3. Click Add, and supply a Computer Name and the MAC address of the spare blade


Click to view.

4. Click OK to close the New Computer Properties Dialog. (A New Computer record is created).


Click to view.

Configure Monitor Solution to Launch the Recovery Job

In this example we'll cover two ways that you can configure an Altiris Monitor Solution rule to launch the spare blade's deployment job. There are two options:

Option 1: The monitor agent on the failing blade can open a browser to launch the Recovery Job

Option 2: Monitor Solution can automatically create a Helpdesk Incident which launches the Recovery Job.

Option 1: Launch Recovery Job Automatically from the Monitor Agent

1. Open the Altiris Notification Server Console, and click on the Tasks tab.
2. Drill down to Tasks –> Monitoring –> Monitor Solution –> Manage Monitor Metrics
3. In the right pane, double-click Dell Server Hardware Management
4. From the Categories Tab, double-click Hardware Device Monitoring
5. From the Rules Tab, double click Global System Status is in a Critical State
6. From the Action Tab, click the New… button
7. Select Execute Command on Agent
8. For an action name: Launch DS Failover Job
9. For the File to execute, provide the following command (all on one line, include the "^" character)

cmd /k (start http://<DSNAME>/dsjob/dsjob_fromurl.asmx/ScheduleNow?ComputerName=spare_blade^&JobName=D_%COMPUTERNAME%_Image)

Note: This call the web service will be automatically triggered whenever the Altiris Monitor Solution agent detects
that the server it is managing enters a critical state as defined by Dell OpenManage Server Administrator.

Option 2: Launch Recovery Job automatically from Helpdesk

1. Open the Altiris Notification Server Console, and click on the Tasks tab.
2. Drill down to Tasks –> Monitoring –> Monitor Solution –> Manage Monitor Metrics
3. In the right pane, double-click the desired monitor pack. (i.e. Dell Server Hardware Management)
4. From the Categories Tab, double-click the desired category (i.e. Hardware Device Monitoring)
5. From the Rules Tab, double click the desired Rule (i.e. Global System Status is in a Critical State)
6. From the Action Tab, click the New… button
7. Select Create Incident
8. For Title: Critical Server Failure
9. Assigned To: Administrator (other fields may be used)
10. Priority: ASAP
11. Comment: Monitor Solution has detected that your server has failed
12. Click OK
13. Click OK

Configuring the Automation Rule in the Altiris Helpdesk

In this example we'll configure the Altiris Helpdesk Solution to launch the Deployment Server Web Service. The Altiris Helpdesk Automation Rules allow you to trigger Web Services or launch any URL based on any criteria of a created or modified Helpdesk ticket. By levering Altiris Helpdesk's Automation Rules administrators can create conditions, use helpdesk tokens, and invoke multiple URLS based on those conditions, providing increased security.

Step 1: Configure the Helpdesk Automation Rule

1. Open the Altiris Notification Server Console, and click on the Incidents tab.
2. From the left side menu, select Admin –> Automation Rules –> New Automation Rules
3. For Name: Server Failure/Reprovisioning Automation Rule
4. Check the Log to Incident checkbox
5. In the "When:" Drop Down List, select "Only when Incident is new".
6. In the "When" conditions section, select Title from the drop down list, and click Add.
7. Check the "When the value of Title:" checkbox
8. Select Contains from the drop down list.
9. Supply the text: Critical Server Failure in the textbox
10. Click OK.
11. In the "Invoke these Urls:" section, click the new ( ) icon.
12. Select Invoke a URL from the URL type drop down list.
13. For Name: Launch DS Failover Job
14. For Base Url: http://localhost/dsjob/dsjob_fromurl.asmx/ScheduleNow
15. In the "URL Parameters" Section, for Name: ComputerName
16. For Value: spare_blade
17. Click Add
18. In the "URL Parameters" Section, for Name: JobName
19. For Value: D_WORKITEM(managed_object_name)_Image
20. In the "Send parameters using:" section, select the POST radio button
21. In the "Credentials:" section, select the Impersonate the worker radio button
22. Click OK
23. Click OK

The Automation Rule settings should resemble the screenshot below.

Click to view.

When the Altiris Monitor Solution Rule is triggered, an Altiris Helpdesk incident will be created. This incident (due to its title) will automatically invoke the correct URL to provision the spare blade in the place of the failing server.

Conclusion

Altiris Deployment Server is a powerful tool that dramatically reduces the cost of deploying and managing Dell hardware. This whitepaper has outlined the steps necessary to create a web service that provides for programmatic, remote execution of Altiris Deployment Server jobs.

This option provides flexibility and integration between Altiris Deployment Server and other Altiris Solutions or third party tools. This paper suggested one possible scenario that could leverage the web service using Altiris Monitor Solution.

When used together Altiris Solutions allow Administrators to take a proactive rather than reactive approach when managing their environments.

Appendix A – Manual Installation

This section will cover how to manually setup and configure the Deployment Server web service.

Copy Required Files

There are 4 required files that make calling a Deployment Server job possible through a web services interface. They are AxDsDm.dll (located in the Deployment Server eXpress share), System.Runtime.Remoting.dll (a Microsoft .NET file), dsjob_fromurl.asmx & web.config. The last two files may be created from the source in Appendix B.

To configure these files, follow the steps below:

Step 1: Create required directories

1. Open the Deployment Server eXpress share (%Program Files%\Altiris\eXpress\Deployment Server\).
2. Create a new directory called dsjob.
3. From within dsjob, create a directory called bin

Step 2: Copy required files

1. Copy the file AxDsDm.dll to the bin directory:

   %Program Files%\Altiris\eXpress\Deployment Server\AxDsDm.dll
   
   

   To

   %Program Files%\Altiris\eXpress\Deployment Server\dsjob\bin\AxDsDm.dll
   
   

   Note: A copy of AxDsDm.dll should still exist in its original location

2. Copy the dsjob_fromurl.asmx and web.config files to the dsjob directory.
   The folder structure should resemble the screenshot below.






Figure 1: Proper directory structure after creating & copying required directories and files.

Click to view.

Creating the Virtual Directory

A virtual directory maps a physical directory on a machine to an http accessible URL. Use the steps below to create a virtual directory that accesses the dsjob folder created earlier.

Step 1: Create the Virtual Directory

1. Open Internet Service Manager (Start –> Run –> inetmgr).
2. Right-click on Default Web Site, select New –> Virtual Directory
3. In the wizard, give the virtual directory the Alias: dsjob
4. In the wizard, provide the patch to the dsjob folder in the eXpress Share:
   

   %Program Files%\Altiris\eXpress\Deployment Server\dsjob
   
   

5. In the wizard, give the virtual directory, Read, Run Scripts, and Execute permissions.
6. Click Next & Finish to complete the wizard.

Step 2: Set the Authentication and access control for the Virtual Directory

1. Open Internet Service Manager (Start –> Run –> inetmgr).
2. Right-click on the Virtual directory, dsjob, and select Properties.
3. On the Directory Security tab, click the top most Edit button, within the Authentication and access control box.
4. Check the Enable Anonymous Access checkbox. (may already be checked)
5. In the Username and Password fields, provide user credentials with access to the eXpress database.


Figure 2: Provide user credentials that will be used when calling the web service.

Click to view.

6. Ensure that Integrated Windows Authentication is checked.
7. Click OK twice, and close the Internet Service Manager.

Step 3: Verifying Your Installation

1. Open Internet Service Manager (Start .. Run .. inetmgr).
2. Select the dsjob virtual directory
3. In the right pane, right-click on dsjob_fromurl.asmx .. Browse
   Internet Explorer will open to the webservice url. Listed will be the available functions from the web service. (See Image)


Click to view.

Appendix B – Web Service Source

Web Service file (dsjob_fromUrl.asmx)

This web service uses the Deployment Server Data Class Library (AxDsDm.dll). Documentation of the classes in this library can be found in the dssdkhelp.chm help file in the Deployment Server eXpress Share, however these classes ARE NOT supported by Altiris.

<%@ WebService Language="c#" Class="dsjob" %>
using System;
using System.Collections;
using System.Collections.Specialized;
using System.Data;
using System.Net;
using System.Reflection;
using System.Runtime.Remoting;
using System.Runtime.Remoting.Activation;
using System.Runtime.Remoting.Channels;
using System.Runtime.Remoting.Channels.Http;
using System.Web;
using System.Web.Services;
using Altiris.DSSDK;

public class dsjob {
   
   static object[] urlAttributes = new object[1];
   
   [WebMethod]
   public string ScheduleNow(string ComputerName, string JobName)
   {
      try
      {
         // If there are any registered channels left over from previous attempts, unregister them now.
         foreach (IChannel thisChannel in ChannelServices.RegisteredChannels)
         {
               ChannelServices.UnregisterChannel(thisChannel);
         }
		 
   HttpClientChannel channel = new HttpClientChannel("Altiris HTTP Binary Connection", new BinaryClientFormatterSinkProvider());
         ChannelServices.RegisterChannel(channel);
		 
         urlAttributes[0] = new UrlAttribute("http://localhost:8080/AltirisDeploymentServer");
         if(SetRunNowSchedule(GetComputerID(ComputerName),GetJobID(JobName)))
               return "Job " + JobName + " scheduled on " + ComputerName + " successfully!";
         else
            return "Error scheduling Job " + JobName + " for " + ComputerName;
      }
      catch(Exception ex)
      {
         return "Error: Scheduling Job " + ex.Message + "-- " + ex.InnerException + "";
      }
   }
   public int GetComputerID(string ComputerName)
   {
      Computer computer = (Computer)Activator.CreateInstance(typeof(Computer), null, urlAttributes);
      DataSet dsComputer = computer.Find(ComputerName);
      if (!dsComputer.Tables.Contains("computer") || dsComputer.Tables["computer"].Rows.Count == 0)
               return -1;
			   
      DataRow drComputer = dsComputer.Tables["computer"].Rows[0];
      int computerID = Convert.ToInt32(drComputer["id"]);
      return computerID;
   }
   public int GetJobID(string JobName)
   {
      Job job = (Job)Activator.CreateInstance(typeof(Job), null, urlAttributes);
      DataSet dsJob = job.Find(JobName);
      if (!dsJob.Tables.Contains("job") || dsJob.Tables["job"].Rows.Count == 0)
               return -1;
      DataRow drJob = dsJob.Tables["job"].Rows[0];
      int jobID = Convert.ToInt32(drJob["event_id"]);
      return jobID;
   }
   public bool SetRunNowSchedule(int compID, int jobID)
   {
      ArrayList al_ScheduleIds = new ArrayList();
      ArrayList al_computerIDs = new ArrayList();
      ArrayList al_jobIDs = new ArrayList();
	  
      al_computerIDs.Add(compID);
      al_jobIDs.Add(jobID);
	  
      Schedule schedule = (Schedule)Activator.CreateInstance(typeof(Schedule), null, urlAttributes);
      bool success = schedule.Add(ref al_ScheduleIds, al_computerIDs, al_jobIDs, Schedule.ScheduleType.RunNow);
	  return success;
   }
}

Web.config file

<configuration>
   <system.web>
      <webServices>
         <protocols>
            <add name="HttpGet"/>
            <add name="HttpPost"/>
         </protocols>
      </webServices>
      <identity impersonate="true" />
   </system.web>
</configuration>