API: Legacy API (for LBMP 5.5 and earlier) |
|
|
|
|
||
|
API: Legacy API (for LBMP 5.5 and earlier) |
|
|
|
|
|
API: Legacy API (for LBMP 5.5 and earlier)
|
API: Legacy API (for LBMP 5.5 and earlier) |
|
|
|
|
||
|
API: Legacy API (for LBMP 5.5 and earlier) |
|
|
|
|
|
Do not use the Legacy API for any new project.
Additions to existing Applications using the Legacy API should be implemented using the new 6.0 API.
Starting with LBMP 6.0, a new API was introduced with security, more provisioning functions and a new imaging capability. It is far superior to the Legacy API.
This page covers the Legacy API that will be supported through July 1, 2011 and then discontinued. We encourage customers to start transitioning from the Legacy API to the new API during this window of time, and to write any new applications using the new API only.
The LinMin Server Application Programming Interface enables external applications (hosting control panels, asset management, load balancing, capacity planning, systems management, cloud computing resource management, system monitoring, SaaS deployment, hosting customer signup/billing, etc.) to interface directly with the LinMin Server data structures, eliminating the need for an IT user to use the graphical user interface for MAC-Specific Provisioning.
The API allows pre-existing Provisioning Role Templates to be assigned (add/update/delete/read) to unique systems based on MAC address, and dynamic, real-time business needs. In this fashion, external applications can prepare systems to be provisioned from a pool of spare or under-utilized systems to maximize system capacity and minimize power consumption. The next time a given system boots to the network, it will be provisioned as specified by the external application, without human intervention.
The API can be used by either incorporating a GUI page into an existing application, or by issuing HTTP commands from an external program to the LinMin Server.
LBMP PROFILES Database Table API Specifications
Module name: lbmp-DBAPI-profiles.php
This PHP based API will get “linminbmp” database "profiles" table records by key and provide basic functions equivalent to the GUI actions --
| 1. | MAC-Specific Provisioning Roles --> Add MAC-Specific Role --> MAC-Specific Provisioning Role {fill in form fields} --> OK |
| 2. | MAC-Specific Provisioning Roles --> Edit {selected} --> MAC-Specific Provisioning Role {change form fields} --> OK |
| 3. | MAC-Specific Provisioning Roles --> Delete {selected} --> OK |
The actions supported are:
| • | read |
| • | add |
| • | delete |
| • | update (no support for record locking with update will be provided so there is no assurance against stepping on interim GUI changes (there is a very low probability of this happening). |
The key accesses supported are:
| • | by user supplied nick name |
| • | by MAC address |
| • | key access will be: |
| • | If mac_address is not present or is null user_supplied_id must be present. |
| • | If both are present the user_supplied_id is used as the access key (an error is thrown if the passed in MAC is not equal to the DB MAC of the user_supplied_id record) |
The "profiles" database fields supported are:
For field details refer to the documentation fore the GUI field names.
| • | user_supplied_id |
| o | key field |
| o | GUI: Nick Name) |
| • | mac_address |
| o | key field |
| o | format ff:ff:ff:ff:ff:ff |
| o | GUI: MAC Address |
| • | node_name |
| o | GUI: Host Name |
| • | node_domain |
| o | GUI: Domain Name Server |
| • | node_password |
| o | GUI: Root Password |
| • | node_ip_address |
| o | format ###.###.###.### |
| o | GUI: IP Address |
| • | node_subnet_mask |
| o | format ###.###.###.### |
| o | GUI: Net Mask |
| • | node_nameserver |
| o | format ###.###.###.### |
| o | GUI: Domain Name Server |
| • | node_default_gateway |
| o | format ###.###.###.### |
| o | GUI: Gateway |
| • | node_time_zone |
| o | values GMT{+1 to +12 or -1 to -12} |
| o | GUI: Time Zone |
| • | control_file_template |
| o | valid existing template |
| o | GUI: Provisioning Role Template |
| • | enable_provisioning_flag |
| o | values: 'ignore', 'always', or 'nextbootonly' |
| o | GUI: Enable Provisioning upon Network Boot? |
| ▪ | values Ignore (boot from local disk), Always Provision, or Provision on next boot only, then set to Ignore |
| • | Table fields not shown will be set to system defaults the same as with the GUI actions |
The protocol supported will be standard HTTP get/post --
| • | Input interfaces supported: |
| o | URL with parameter string |
| ▪ | url/lbmp-DBAPI-profiles.php?name1=value1&name2=value2... |
| • | values must be url encoded |
| o | HTML form, POST or GET |
| o | CGI HTTP |
| o | PHP CLI with a single quoted parameter string equivalent to a URL GET string of name value pairs |
| • | Output interface will be HTTP URL with GET format name value parameter string. |
| o | Values will be encoded |
Fields passed as input are --
| • | Required for all actions: |
| o | action={read, add, update, delete} |
| o | an access key |
| ▪ | user_supplied_id |
| ▪ | or |
| ▪ | mac_address={valid mac in correct format} |
| • | Additionally for "update" actions |
| o | Any remaining supported fields with new values |
| • | Other "update" action fields supported – changes to key fields |
| o | new_mac_address |
| ▪ | format ff:ff:ff:ff:ff:ff |
| ▪ | GUI: MAC Address |
| o | new_user_supplied_id |
| ▪ | GUI: Unique System Nickname |
| • | Additionally for "add" actions |
| o | All remaining supported fields are required with values |
| • | Optionally this field may be passed: |
| o | returnURL={urlencoded URL} |
| ▪ | The default is to return to the referring URL if returnURL is not present or is null |
Return parameters are:
| • | action={same as input} |
| • | actionResults={OK or FAILED} |
| • | actionResultsMsg={text, success message or error message} |
| • | mac_address={from DB or same as input on failure} |
| • | user_supplied_id={from DB or same as input on failure} |
| • | For action "read" with actionResults "OK" -- |
| o | all other supported fields are returned with values from the DB |
| • | For actions other than "read" with all actionResults values -- |
| o | all input fields are returned with values passed in |
Example actionResults and actionResultsMsg:
| • | actionResults=OK with actionResultsMsg=Successful:update |
| • | actionResults=OK with actionResultsMsg=Successful:delete |
| • | actionResults=OK with actionResultsMsg=Successful:add |
| • | actionResults=FAILED with actionResultsMsg=add: record already exists for user_supplied_id: centos51-1 |
| • | actionResults=OK with actionResultsMsg=Successful:delete |
| • | actionResults=FAILED with actionResultsMsg=delete: delete failed, no record found for: WHERE user_supplied_id = 'centos51-1' |
Logging actions:
| ► | A log file of the result status of each API call is maintained at the default location |
| ► | /usr/local/linmin/lbmp-DBAPI-profiles.log |
| ► | This location may be changed in the file |
| ► | /usr/local/linmin/lbmp-DBAPI-profiles_log_location.cfg |
| ♦ | if this cfg file does not exist creating it with a valid path/name will establish the log |
| ► | To turn off logging enter '/dev/null/' in |
| ► | /usr/local/linmin/lbmp-DBAPI-profiles_log_location.cfg |
Example log entries:
2008-07-27_23:24:55_PDT MAC:ff:00:00:00:00:01 Nickname:centos51-1 Status:OK Successful:update 2008-07-27_23:31:22_PDT Nickname:centos51-1 Status:OK Successful:delete 2008-07-27_23:31:41_PDT MAC:ff:00:00:00:00:01 Nickname:centos51-1 Status:OK Successful:add
2008-07-27_23:31:43_PDT MAC:ff:00:00:00:00:01 Nickname:centos51-1 Status:FAILED add: record already exists for user_supplied_id: centos51-1
2008-07-27_23:32:52_PDT Nickname:centos51-1 Status:OK Successful:delete
2008-07-27_23:32:55_PDT Nickname:centos51-1 Status:FAILED delete: delete failed, no record found for: WHERE user_supplied_id = 'centos51-1'
Interactive use learning via example GUI (lbmp-DBAPI_sample_URL_string_generator.php) form:
(this page is no longer shipped with LBMP but it remains on your LinMin Server after you upgrade to 6.0 and beyond)
The LinMin Server provides a PHP example API interface form module. This is to be used to explore and learn about the API actions and requirements. If familiar with the LinMin Server GUI for MAC-Specific Provisioning Role this form will intuitive. It mostly mirrors the fields and actions of MAC-Specific Provisioning Role GUI as described in the users guide.
| ► | Module name: lbmp-DBAPI_sample_URL_string_generator.php |
| ► | Invoke via browser |
| ► | http://{yourLBMPserverIP}/tftpboot/www/lbmp-DBAPI_sample_URL_string_generator.php |
| ► | Read the notes at the bottom of the form for an understanding of the differences from actual MAC-Specific Provisioning Role GUI. |
| ► | The differences to note are in these form rows: |
| ► | Results of previous action |
| ♦ | shows the results of the previous action |
| ► | New System Nickname |
| ♦ | allows for changing this key field |
| ► | New MAC Address |
| ♦ | allows for changing this key field |
| ► | Provisioning Role Template |
| ♦ | a drop-down selection in the LinMin Server GUI, this must be known and keyed in this form |
| ► | Action |
| ♦ | provides for the basic actions, Read, Update, Add, and Delete |
| ► | Debug |
| ♦ | No |
| • | call to API with direct return the submit form displaying returned values |
| ♦ | Show |
| • | call to API showing detail information about the construction of the URL return string |
| • | provides a clickable link to continue to the submit form displaying returned values |
| ♦ | GET |
| • | call to the API showing the input and output HTTP GET format parameter strings |
| • | provides a clickable link to continue to the submit form displaying returned values |
| ♦ | GET example |
| • | Invoked with HTTP GET string: |
returnURL=http%3A%2F%2F192.168.1.56%2Ftftpboot%2Fwww%2Flbmp-DBAPI_sample_URL_string_generator.php &user_supplied_id=&mac_address=&new_user_supplied_id=&new_mac_address=&control_file_template=&node_name=&node_domain=&node_ip_address=&node_subnet_mask=&node_nameserver=&node_default_gateway=&node_password=&node_time_zone=&action=read
| • | Returns with HTTP GET string: |
returnURL=http%3A%2F%2F192.168.1.56%2Ftftpboot%2Fwww%2Flbmp-DBAPI_sample_URL_string_generator.php&user_supplied_id=&mac_address=&new_user_supplied_id=&new_mac_address=&control_file_template=&node_name=&node_domain=&node_ip_address=&node_subnet_mask=&node_nameserver=&node_default_gateway=&node_password=&node_time_zone=&action=read&actionResults=FAILED&actionResultsMsg=update%253A%2Bno%2Bkey%2Bprovided%252C%2Buser_supplied_id%2Bor%2Bmac_address%2Brequired
Examples of a completed API code generation page:
And the corresponding output: