Cisco Server Provisioner's API access is restricted to known IP addresses and requires authorization tokens called APIDs (short for API IDs.)

 

APIDs are created and managed via a script available only to the root user on the Provisioner PXE Server. After providing a user name, password and the IP address(es) of the server(s) running your application that interacts with the Provisioner PXE Server API, you will be issued an APID.

 

Collectively, the APID, your user name and password can be used at any time to request access to the Provisioner PXE Server API. These credentials must accompany any request your application makes of the Provisioner PXE Server API to perform any supported Provisioning or Imaging action (read, add, delete, provision, backup, etc.)

 

This Topic covers how to create, maintain and delete Authorization.

 

 

Logged in as root:

cd /home/tftpboot/www

php lbmp-API-APID-admin.php help

 

The help option shows you the command format and examples of usage. The following is the output from the help option:

v34 2013-06-19 lbmp-API-APID-admin.php Help via command: 'php lbmp-API-APID-admin.php help'

 

Command Format:

 

# php lbmp-API-APID-admin.php action=[adduser deluser addips delips getips listusers] [user={user-name}] [pwd={password}] [apid={access-apid}] [ips={ip1[,ip2 ...]}]

 

Notes:

* Parameters are not position dependent (they are all name=value pairs)

* 'user' names must be unique, 8 plus characters, and contain no prohibited special characters

* 'pwd' passwords must be 8 plus characters and contain no prohibited special characters

* converted old format APID records may have user and pwd shorter than 8 characters

* changing a password requires a 'deluser' and 'adduser' which will create a new APID for IPs registered to that user

* See examples for required parameters with each action

 

--- STDOUT Return Formats ---

 

Success:

 

rtncode=0 rtnmsg='OK:{action} {messages}' [other name=value or name='value' pairs]

 

Failure:

 

rtncode={non-zero-number} rtnmsg='{ERROR:{action} E:message1[E:message2 ...]}' [other name=value or name='value' pairs]

 

 

--- Examples with Notes ---

 

Example: 1) See all users with complete information when converted old format entries to new format exist

# php lbmp-API-APID-admin.php action=listusers

# API Users:

user=rico pwd=sez2 apid=10418a5b6e301ea7d12b9a3146459f5e ips=192.168.1.250 lastchange=20130323-014647 oldAuthApid=81333e55addbb1ae8d646b5172b535ad

user=ricoman pwd=sez2 apid=71f464dd44d9740db7abbfa93efe7aee ips=192.168.1.61 lastchange=20130323-014647 oldAuthApid=b9c644121e0b0a081a0d96fd29dc867e

rtncode=0 rtnmsg='OK:listusers'

 

Notes:

* APIDS with 'oldAuthApid={apid}' are old format APIDs and may have duplicated user and pwd

* When no users exist the list will be empty

# API Users:

rtncode=0 rtnmsg='OK:listusers'

 

 

Example: 2) Add a user

# php lbmp-API-APID-admin.php action=adduser user=username1 pwd=password1 ips=192.168.2.25

Returns --

rtncode=0 rtnmsg='OK:adduser' apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.2.25

 

Example: 3) See all users with complete information

# php lbmp-API-APID-admin.php action=listusers

Returns --

# API Users:

user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.2.25 lastchange=20130227-131306

rtncode=0 rtnmsg='OK:listusers '

 

 

Example: 4) Add IPs to a user

# php lbmp-API-APID-admin.php action=addips user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.2.26,192.168.1.27,192.168.1.28

Returns --

rtncode=0 rtnmsg='OK:addips 192.168.2.26,192.168.1.27,192.168.1.28 W:IP already exists 192.168.2.26 W:IP already exists 192.168.1.27 W:IP already exists 192.168.1.28' ips=192.168.1.27,192.168.1.28,192.168.2.25,192.168.2.26

 

 

Example: 5) Get User IPs

# php lbmp-API-APID-admin.php action=getips user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7

Returns --

rtncode=0 rtnmsg='OK:getips' ips=192.168.1.27,192.168.1.28,192.168.2.25,192.168.2.26

 

 

Example: 6) Add IPs to a user with invalid IP(s)

# php lbmp-API-APID-admin.php action=addips user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.2.251,192.168.2.288,192.168.210

Returns --

rtncode={non-zero-number} rtnmsg='ERROR:addips E:invalid IP 192.168.2.288 E:invalid IP 192.168.210'

 

Note: No IPs are added if any are invalid

 

 

Example: 7) Delete IPs from a user

# php lbmp-API-APID-admin.php action=delips user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.1.28

Returns --

rtncode=0 rtnmsg='OK:delips 192.168.1.28' ips=192.168.1.27,192.168.2.25,192.168.2.26

 

 

Example: 8) Delete IPs from a user with IP(s) not found and invalid IP(s)

# php lbmp-API-APID-admin.php action=delips user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.2.251,192.168.2.288

Returns --

rtncode={non-zero-number} rtnmsg='ERROR:delips E:invalid IP 192.168.2.288'

 

Note: No IPs are deleted if any are invalid

 

 

Example: 9) Any action request where authorization fails due to invalid apid or user

# php lbmp-API-APID-admin.php action=getips user=username1X pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7

Returns --

rtncode={non-zero-number} rtnmsg='ERROR:getips E:invalid apid or user'

OR

# php lbmp-API-APID-admin.php action=getips user= pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7

rtncode={non-zero-number} rtnmsg='ERROR:getips E:missing user value'

 

 

Example: 10) Delete a user

# php lbmp-API-APID-admin.php action=deluser user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7

Returns --

rtncode=0 rtnmsg='OK:deluser' user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7 ips=192.168.1.27,192.168.2.25,192.168.2.26 lastchange=20130323-031929

 

Example: 11) Any action request with apid= required and an invalid APID (no matching record)

# php lbmp-API-APID-admin.php action={action-request} user=username1 pwd=password1 apid=1214c12e4923ed67b098b8a71a0805a7

Returns --

rtncode={non-zero-number} rtnmsg='ERROR:{action-request} E:apid is invalid, no record found E:invalid apid or user'

 

 

# SEE USERS GUIDE for more details - search 'APID'

................................................................................

 

 

 

Following the example in Help, create an APID with its associated user name, password and IP address(es).

 

[root@baremetalgui www]# php lbmp-API-APID-admin.php action=adduser user=linmin99 pwd=linmin99 ips=192.168.1.7,192.168.1.8

rtncode=0 rtnmsg='OK:adduser' apid=ec056b1970d3cc7238a52a65c42d3b65 ips=192.168.1.7,192.168.1.8

 

 

You will now use your APID, user name and password to perform functions with the Provisioner API.