Project

General

Profile

API » History » Version 16

Corey Osman, 09/09/2012 10:43 PM

1 1 Ohad Levy
h1. API
2
3
Foreman Smart Proxy provides a "REST":http://en.wikipedia.org/wiki/Representational_State_Transfer API, communicating via JSON.
4
5
Please refer to this document for latest information about Foreman Smart Proxy API.
6
7 10 Paul Kelly
_The API entries containing *variant* are only available in smart-proxy v2.0 and later._
8
9 1 Ohad Levy
h2. List of API's
10
11
|_.Path|_.REST Type|_.Description|_.Example Input JSON|  
12
|_.FEATURES |
13
|/features|GET|List of features supported by the proxy||
14 9 Ohad Levy
|/version|GET|Proxy version||
15 1 Ohad Levy
|_.DHCP |
16
|/dhcp|GET|Retrieve a list of subnets||
17
|/dhcp/10.1.2.0|GET|Retrieve 10.1.2.0 subnets records||
18
|/dhcp/10.1.2.0/10.1.2.5|GET|Retrieve 10.1.2.5 reservation information ||
19
|/dhcp/10.1.2.0/unused_ip|GET|Provides an unused ip address in 10.1.2.0 subnet ||
20 5 Frank Sweetser
|/dhcp/10.1.2.0|POST|creates new reservation in 10.1.2.0 subnet |@{"hostname":string, "name":string, "filename":string, "ip":string, "nextserver":string, "mac":string}@|
21 1 Ohad Levy
|/dhcp/10.1.2.0/10.1.2.5|DELETE|Deletes 10.1.2.5 reservation from 10.1.2.0 subnet||
22
|_.DNS |
23 11 Michael Coulter
|/dns/|POST|Create a new DNS record|@{"fqdn":string(name/ip), "value":string(ip/reverse), "type":string(A/PTR)}@|
24 1 Ohad Levy
|/dns/value|DELETE|remove value(ip or reverse) DNS record||
25
|_.TFTP |
26 10 Paul Kelly
|/tftp/00:11:22:33:44:55|POST|creates pxelinux configuration file for host with MAC address 00:11:22:33:44:55|@{"syslinux_config":string}@. Implicit variant of "syslinux"|
27
|/tftp/<variant>/00:11:22:33:44:55|POST|creates pxeconfig configuration file for host with MAC address 00:11:22:33:44:55|@{"pxeconfig":string}@. Variant can be "syslinux" or "pxegrub"|
28
|/tftp/00:11:22:33:44:55|DELETE|remove pxelinux configuration file for host with MAC address 00:11:22:33:44:55|Implicit variant of "syslinux"|
29
|/tftp/<variant>/00:11:22:33:44:55|DELETE|remove pxeconfig configuration file for host with MAC address 00:11:22:33:44:55|. Variant can be "syslinux" or "pxegrub"|
30
|/tftp/create_default|POST|creates a default pxelinux configuration file|@{"syslinux_config":string}@. Implicit variant of "syslinux" |
31
|/tftp/<variant>/create_default|POST|creates a default pxeconfig configuration file|@{"pxeconfig":string}@. Variant can be "syslinux" or "pxegrub"|
32 5 Frank Sweetser
|/tftp/fetch_boot_file|POST|creates a default pxelinux configuration file|@{"prefix":string, "path":string}@|
33 8 Ohad Levy
|/tftp/serverName|GET|fetches the TFTP server name to be used within a dhcp record||
34 1 Ohad Levy
|_.PUPPET CA |
35
|/puppet/ca|GET| list of all puppet certificates ||
36 7 Ohad Levy
|/puppet/ca/certname|POST| Sign pending certificate request ||
37
|/puppet/ca/certname|DELETE| Remove (clean) and revoke a certificate ||
38 1 Ohad Levy
|/puppet/ca/autosign|GET| list of all puppet autosign entires ||
39
|/puppet/ca/autosign/certname|POST| Add certname to Puppet autosign ||
40
|/puppet/ca/autosign/certname|DELETE| Remove certname from Puppet autosign ||
41
|_.PUPPET |
42 5 Frank Sweetser
|/puppet/run|POST| Trigger puppet run / kick|@["hostA", "hostB"]@|
43 12 Ohad Levy
|/puppet/environments |GET| list of all puppet environment names||
44
|/puppet/environments/production> |GET| show puppet production environment name and module paths||
45 13 Ohad Levy
|/puppet/environments/production/classes |GET| return a hash of puppet classes in the production environment|Puppet class parameters is supported from 1.1|
46 15 Corey Osman
|_.BMC |
47 16 Corey Osman
|/bmc/providers|GET|Get a list of supported BMC providers||
48
|/bmc/providers/installed|GET|Get a list of installed BMC providers||
49
|/bmc/:host|GET|returns host operations||
50
|/bmc/:host/chassis|GET|returns chassis operations||
51
|/bmc/bmc/:host/chassis/power/:action|GET|Gets the power status, does not change power, leave action blank for list of available actions||
52
|/bmc/:host/lan/?:action|GET|Get bmc lan details, leave action blank for list of available actions||
53
|/bmc/:host/chassis/identify/:action|GET|gets chassis identify status, leave action blank for list of available actions||
54
|/bmc/:host/chassis/config/:function|GET|Get chassis config details, supports bootdevices, leave function blank for list of available functions||
55
|/bmc/:host/chassis/power/:action|PUT|Control the power of the bmc device, leave action blank for list of available functions| valid actions: on, off, cycle, soft|
56
|/bmc/:host/chassis/config/:function/:action|PUT|Set config of bios, currently supports bootdevice|valid actions: pxe, cdrom, bios, disk   valid options: reboot, persistent|
57
|/bmc/:host/chassis/identify/:action|PUT|controls the chassis identify light, leave action blank for available actions| actions: on, off|
58 15 Corey Osman
59 1 Ohad Levy
60
Please raise a new issue if you need additional API's
61 4 Frank Sweetser
62
h2. Manually Calling the API
63
64
The API can be manually tested out using curl.  GET types can be retrieved like any other URL.  This one, for example, will return the HTML formatted page with the list of features enabled on the proxy.
65
66 1 Ohad Levy
<pre>
67
curl http://localhost:8443/features
68
</pre>
69
70 14 Michael Coulter
The results can also be returned as JSON if you set an appropriate Accept header.
71
72
<pre>
73
curl -H "Accept: application/json" http://localhost:8443/features
74
</pre>
75
76 1 Ohad Levy
POST URLs, used to create objects or trigger actions, need to have the parameters passed in via the -d argument.  This curl command line will trigger a puppetrun on server.example.com.
77
<pre>
78
curl -d 'nodes=server.example.com' http://localhost:8443/puppet/run
79 11 Michael Coulter
</pre>
80
81
This curl command line will add an A record for server.example.com with ip address of 10.1.2.5.
82
<pre>
83
curl -d 'fqdn=servers.example.com&value=10.1.2.5&type=A' http://localhost:8443/dns/
84 5 Frank Sweetser
</pre>
85
86
Multiple post options may be specified by repeating the -d argument.
87
<pre>
88
curl -d 'prefix=boot/CentOS-5-x86_64' -d 'path=http://yourlocalmirrorhere/pub/centos/5/os/x86_64/images/pxeboot/vmlinuz'  http://localhost:8443/tftp/fetch_boot_file
89
</pre>
90
91
When you are creating an object, the identifier for the object is typically passed in as part of the URL, rather than as a POST value.  For example, this will create a PXE boot configuration file for a host with MAC address 00:11:22:33:44:55, and will just put "Hello World" as the contents of the file.  (A real world example would, of course, substitute a valid PXE boot configuration in the string.)
92
93
<pre>
94
curl -d 'syslinux_config=Hello World' http://localhost:8443/tftp/00:11:22:33:44:55
95
</pre>
96
97
In order to delete objects, you use the same URL as in the original creation, but pass it not POST values, and use the DELETE HTTP method instead of POST.  This will delete the PXE boot configuration file created above.
98
99
<pre>
100 1 Ohad Levy
curl -X DELETE http://localhost:8443/tftp/00:11:22:33:44:55
101
</pre>
102 16 Corey Osman
103
h2. BMC Controls 
104
105
Summary
106
The smart-proxy can now control BMC devices through the use of the IPMI protocol.  The smart proxy utilizes ipmitool and freeipmi to control your BMC devices through the network.  
107
108
h3. Prerequisites
109
110
In order to control the BMC device using the smart proxy you must perform the following actions:
111
112
1. Enable bmc support in the settings.yml file
113
2. Install rubyipmi gem, 
114
3. Install freeipmi, and/or ipmitool either from source or package
115
4. The bmc device must be setup on the network with login credentials
116
5. Smart proxy must be able to reach the bmc device through the network
117
118
h3. Using Parameters with the BMC API
119
120
1. When using the bmc api, you must send the credentials of the bmc device using Http Basic Authorization
121
2. If you wish to override the default bmc provider for a particular BMC device please specify in the http parameter (bmc_provider) Valid options are ipmitool and freeipmi
122
3. Some api calls have optional parameters, leaving the action blank on some api calls will return valid actions and options.
123
124
h2. BMC Security
125
126
Its important to note that at this time the bmc api does not encrypt your credentials.  Your credentials are sent in the clear to the smart proxy and then used on the command line to execute the local command.
127
In order to achieve some level of security it is important that your smart proxy use https.  Using https will ensure that your credentials are sent via the encrypted https channel.  Additionally, by default the bmc api 
128
will never expose your credentials to prying eyes via logs or process checks.  The local bmc commands will be run with the credentials placed in a random file which is deleted upon every call and cannot be opened
129
by any other user.
130 6 Brian Gupta
131
[[Draft 2.0 version of DNS API]]