Note: before using the API, it is important that you review individual provisioning tutorials (by OS, in "Create a MAC-Specific Provisioning Template and Role") so you understand Provisioner functionality and limitations when using the GUI.

 

Use the API Provisioning Example Generator to generate sample code to simplify the integration of Cisco Server Provisioner into your application.

 

The Example Generator produces 2 code samples showing how to call the Provisioner API from your application for each possible type of Provisioner function supported by the API (e.g., read, update, delete, etc.):

•Invoking the API through a browser

•Invoking the API through a wget call from a Linux system

•All field contents must be URL-encoded. It is recommended that all values pass through an encoding process.

 

The Example Generator also produces 2 code samples showing how the Provisioner API will reply to your application:

•XML with UTF-8-encoded values

•URL-encoded GET string

 

 

Before beginning to generate examples with the Generator, be sure you have obtained an APID.

 

Also, make sure that you have created at least one Provisioning Template prior to using the GUI beforehand.

 

 

Accessing the Provisioning Example Generator

 

Starting with the Chuck Berry Plus package, the Provisioning Example Generator is accessed from the Application GUI Main Menu:

 

 

 

Note: for Provisioner 6.5.1 not upgraded with the Chuck Berry Plus package: the API Provisioning Example generator can be accessed with your browser:

http://{Provisioner-server-IP}/tftpboot/www/lbmp-API_provisioning_example_generator.php

 

 

 

Then, complete the form and specify the Return Format of your choice and the desired action to be taken by the Provisioner PXE Server. In this case, we are adding a MAC-Specific Provisioning Role and will have a system provisioned with Windows Server 2008 R2:

 

 

 

Sample code generated for your application to call the Provisioner PXE Server API (replace "XXXXXXXX" values with valid values):

 

•HTTP call:

http://192.168.1.8/tftpboot/www/lbmp-API.php?actiontype=provision&user_supplied_id=box227&mac_address=00%3A50%3A56%3A3C%3AA0%3A92&apid=ec056b1970d3cc7238a52a65c42d3b65&auth_user=XXXXXXXX&user_ips=192.168.1.7&control_file_template=Windows+Server+2008+R2+SERVERENTERPRISE+-+w2k8r2&node_name=box227&node_domain=store.appcloud.com&node_ip_address=DHCP&node_password=XXXXXXXX&node_time_zone=Etc%2FGMT&enable_provisioning_flag=ignore&rtn_format=XML&action=add&node_subnet_mask=DHCP&node_nameserver=DHCP&node_default_gateway=DHCP

 

•wget call:

tmpfile=tempwget.txt; wget -qO $tmpfile --post-data 'actiontype=provision&user_supplied_id=box227&mac_address=00%3A50%3A56%3A3C%3AA0%3A92&apid=ec056b1970d3cc7238a52a65c42d3b65&auth_user=XXXXXXXX&user_ips=192.168.1.7&control_file_template=Windows+Server+2008+R2+SERVERENTERPRISE+-+w2k8r2&node_name=box227&node_domain=store.appcloud.com&node_ip_address=DHCP&node_password=XXXXXXXX&node_time_zone=Etc%2FGMT&enable_provisioning_flag=ignore&rtn_format=XML&action=add&node_subnet_mask=DHCP&node_nameserver=DHCP&node_default_gateway=DHCP' http://192.168.1.8/tftpboot/www/lbmp-API.php; cat $tmpfile; rm -f $tmpfile

 

 

 

Sample code generated for the Provisioner PXE Server API to return to your application:

 

•XML with UTF-8 encoded values (password values as 8 Xs):

 

<?xml version="1.0" encoding="utf-8" ?>

<LinMinBareMetalAPI>

<actiontype>provision</actiontype>

<apid>1214c12e4923ed67b098b8a71a0805a7</apid>

<rtn_format>XML</rtn_format>

<action>read</action>

<actionResults>OK</actionResults>

<actionResultsMsg>Successful:read :</actionResultsMsg>

<user_supplied_id>box227</user_supplied_id>

<mac_address>00:50:56:36:5a:37</mac_address>

<auth_user>XXXXXXXX</auth_user>

<control_file_template>Windows Server 2008 R2 SERVERENTERPRISE - w2k8r2</control_file_template>

<node_name>box227</node_name>

<node_domain>store.appcloud.com</node_domain>

<node_ip_address>DHCP</node_ip_address>

<node_subnet_mask>DHCP</node_subnet_mask>

<node_nameserver>DHCP</node_nameserver>

<node_default_gateway>DHCP</node_default_gateway>

<node_time_zone>Etc/GMT</node_time_zone>

<enable_provisioning_flag>ignore</enable_provisioning_flag>

<auth_user_pw>XXXXXXXX</auth_user_pw>

<node_password>XXXXXXXX</node_password>

<pxe_event_ip></pxe_event_ip>

<pxe_event_state>No_PXE_Event_Scheduled</pxe_event_state>

<pxe_event_date_time></pxe_event_date_time>

</LinMinBareMetalAPI>

 

 

•URL encoded GET string format (password values as 8 Xs):

 

actiontype=provision&user_supplied_id=box227&mac_address=00%3A50%3A56%3A36%3A5a%3A37&apid=1214c12e4923ed67b098b8a71a0805a7&auth_user=XXXXXXXX&control_file_template

=Windows+Server+2008+R2+SERVERENTERPRISE+-+w2k8r2&node_name=box227&node_domain=store.appcloud.com

&node_ip_address=DHCP&node_subnet_mask=DHCP&node_nameserver=DHCP&node_default_gateway=DHCP

&node_time_zone=Etc%2FGMT&enable_provisioning_flag=ignore&rtn_format=URL&action=read

&auth_user_pw=XXXXXXXX&node_password=XXXXXXXX&pxe_event_state=No_PXE_Event_Scheduled

&actionResults=OK&actionResultsMsg=Successful%3Aread+%3A

 

Note: name-value pair, also known as "name quoted value with UTF-8 encoded values" is being deprecated (even though they may appear in the example generator).

 

Now you have the syntax for how to call the Provisioner PXE Server API and for how the Provisioner PXE Server API will respond to your application.

 

 

 

Other Provisioning API actions

 

 

Next Boot Actions for each system:

•Ignore (boot from local disk, never re-provision)

•Provision on the next netboot, then ignore future provisioning requests

•Deploy Live Ubuntu into the RAM of the client system

 

 

API functions:

•Read (information on an existing system, given the MAC address or Nickname)

•Update (information on an existing system, given the MAC address or Nickname)

•Add (a system and create a Provisioning Role in the database)

•Delete (a system, given MAC or Nickname)

•List Roles: return list and information on all systems

•List Templates: returns the list of all existing Provisioning Templates

•New starting with Provisioner 6.3 PXE Event States: the API automatically returns the PXE Event State during "Read" (initially for Windows Server 2008/R2, ESX/ESXi, RHEL/CentOS). API supports the ability to force the freeing of a PXE Event IP after relocating a provisioned system from the Provisioning VLAN to a Production VLAN.

•Add APID User IPs authorized to make API calls

•Get APID User IPs authorized to make API calls

•Delete APID User IPS authorized to make API calls

 

 

 

Force Free PXE Event IP:

 

•Free or release PXE IP addresses to override DHCP address reservation for an aborted or failed PXE event with Update Role action

 

 

GUI Interaction:

It is very easy to see if your API call had the intended effect on systems by looking at the Provisioner PXE Server GUI (refresh pages after you have made API calls).

 

Please read all about MAC-Specific Provisioning in general as well as for each operating system you will be provisioning to provide you with the best information while integrating Cisco Server Provisioner into your application.

 

API Log can be found at:

/usr/local/linmin/lbmp-API.log