Project

General

Profile

API » History » Version 39

Dominic Cleal, 05/24/2017 04:19 AM
add DHCP delete by IP/MAC routes

1 1 Ohad Levy
h1. API
2
3 20 Stephen Benjamin
Foreman Smart Proxy provides a "REST":http://en.wikipedia.org/wiki/Representational_State_Transfer API, communicating via JSON.  For providers that take POST requests, some take form parameters as inputs (var=1&var=2), others may take JSON. Please refer to this document for latest information about Foreman Smart Proxy API.
4 1 Ohad Levy
5 10 Paul Kelly
_The API entries containing *variant* are only available in smart-proxy v2.0 and later._
6 1 Ohad Levy
7
h2. List of API's
8
9 20 Stephen Benjamin
|_.Path|_.REST Type|_.Description|_.Example Input |  
10
|
11 1 Ohad Levy
|_.FEATURES |
12
|/features|GET|List of features supported by the proxy||
13 9 Ohad Levy
|/version|GET|Proxy version||
14 1 Ohad Levy
|_.DHCP |
15
|/dhcp|GET|Retrieve a list of subnets||
16
|/dhcp/10.1.2.0|GET|Retrieve 10.1.2.0 subnets records||
17
|/dhcp/10.1.2.0/10.1.2.5|GET|Retrieve 10.1.2.5 reservation information ||
18 37 Klaas D
|/dhcp/10.1.2.0/unused_ip|GET|Provides an unused ip address in 10.1.2.0 subnet |mac=00:00:00:00:00:00&from=10.1.2.3&to=10.1.2.254|
19 33 Klaas D
|/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}@|
20 39 Dominic Cleal
|/dhcp/10.1.2.0/10.1.2.5|DELETE|Deletes 10.1.2.5 reservation from 10.1.2.0 subnet (deprecated since 1.15.0)||
21
|/dhcp/10.1.2.0/ip/10.1.2.5|DELETE|Deletes 10.1.2.5 IP address reservation from 10.1.2.0 subnet (available since 1.15.0)||
22
|/dhcp/10.1.2.0/mac/00:11:22:33:44:55|DELETE|Deletes 00:11:22:33:44:55 MAC address reservation from 10.1.2.0 subnet (available since 1.15.0)||
23 1 Ohad Levy
|_.DNS |
24 20 Stephen Benjamin
|/dns/|POST|Create a new DNS record|@fqdn=hostname.example.com&value=192.168.1.1&type=A@|
25 38 Dominic Cleal
|/dns/value|DELETE|remove DNS record for value (IP or reverse), guessing either PTR or A record||
26
|/dns/value/type|DELETE|remove value DNS record, for a given record type (e.g. AAAA)||
27 1 Ohad Levy
|_.TFTP |
28 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"|
29
|/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"|
30
|/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"|
31
|/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"|
32
|/tftp/create_default|POST|creates a default pxelinux configuration file|@{"syslinux_config":string}@. Implicit variant of "syslinux" |
33
|/tftp/<variant>/create_default|POST|creates a default pxeconfig configuration file|@{"pxeconfig":string}@. Variant can be "syslinux" or "pxegrub"|
34 5 Frank Sweetser
|/tftp/fetch_boot_file|POST|creates a default pxelinux configuration file|@{"prefix":string, "path":string}@|
35 8 Ohad Levy
|/tftp/serverName|GET|fetches the TFTP server name to be used within a dhcp record||
36 1 Ohad Levy
|_.PUPPET CA |
37
|/puppet/ca|GET| list of all puppet certificates ||
38 7 Ohad Levy
|/puppet/ca/certname|POST| Sign pending certificate request ||
39
|/puppet/ca/certname|DELETE| Remove (clean) and revoke a certificate ||
40 1 Ohad Levy
|/puppet/ca/autosign|GET| list of all puppet autosign entires ||
41
|/puppet/ca/autosign/certname|POST| Add certname to Puppet autosign ||
42
|/puppet/ca/autosign/certname|DELETE| Remove certname from Puppet autosign ||
43
|_.PUPPET |
44 5 Frank Sweetser
|/puppet/run|POST| Trigger puppet run / kick|@["hostA", "hostB"]@|
45 12 Ohad Levy
|/puppet/environments |GET| list of all puppet environment names||
46
|/puppet/environments/production> |GET| show puppet production environment name and module paths||
47 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|
48 15 Corey Osman
|_.BMC |
49 16 Corey Osman
|/bmc/providers|GET|Get a list of supported BMC providers||
50
|/bmc/providers/installed|GET|Get a list of installed BMC providers||
51
|/bmc/:host|GET|returns host operations||
52
|/bmc/:host/chassis|GET|returns chassis operations||
53 19 Daniel Lobato Garcia
|/bmc/:host/chassis/power/:action|GET|Gets the power status, does not change power, leave action blank for list of available actions||
54 18 Corey Osman
|/bmc/:host/lan/:action|GET|Get bmc lan details, leave action blank for list of available actions||
55 1 Ohad Levy
|/bmc/:host/chassis/identify/:action|GET|gets chassis identify status, leave action blank for list of available actions||
56
|/bmc/:host/chassis/config/:function|GET|Get chassis config details, supports bootdevices, leave function blank for list of available functions||
57
|/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|
58
|/bmc/:host/chassis/config/:function/:action|PUT|Set config of bios, currently supports bootdevice|valid actions: pxe, cdrom, bios, disk   valid options: reboot, persistent|
59 16 Corey Osman
|/bmc/:host/chassis/identify/:action|PUT|controls the chassis identify light, leave action blank for available actions| actions: on, off|
60 20 Stephen Benjamin
|_.REALM |
61
| /realm/:realm | POST | Creates/Updates new realm entry. "Userclass" is an arbitrary data field.  Used by FreeIPA provider for automembership, and foreman passes the host group title. | @hostname=host.example.com&userclass=webservers@ |
62
| /realm/:realm | POST | Recreate realm entry (revokes keytab, etc) | @hostname=host.example.com&userclass=webservers&rebuild=true@ |
63
| /realm/:realm/:hostname | DELETE | Deletes new realm entry ||
64 36 Lukas Zapletal
|_.LOGS |
65
| /logs/ | GET | Returns proxy log buffer (last N log records) | @{"info": {}, "logs": [{ "timestamp": 1455783010.8100047, "level": "ERROR", "message": "...", "backtrace": "..." }]}@ |
66 1 Ohad Levy
67
Please raise a new issue if you need additional API's
68 4 Frank Sweetser
69
h2. Manually Calling the API
70
71
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.
72
73 1 Ohad Levy
<pre>
74
curl http://localhost:8443/features
75
</pre>
76
77 14 Michael Coulter
The results can also be returned as JSON if you set an appropriate Accept header.
78
79
<pre>
80
curl -H "Accept: application/json" http://localhost:8443/features
81
</pre>
82
83 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.
84
<pre>
85
curl -d 'nodes=server.example.com' http://localhost:8443/puppet/run
86 11 Michael Coulter
</pre>
87
88
This curl command line will add an A record for server.example.com with ip address of 10.1.2.5.
89
<pre>
90
curl -d 'fqdn=servers.example.com&value=10.1.2.5&type=A' http://localhost:8443/dns/
91 5 Frank Sweetser
</pre>
92
93 22 Johan Sunnerstig
This curl command line will remove the A record added above.
94
<pre>
95
curl -XDELETE http://localhost:8443/dns/servers.example.com
96
</pre>
97
98 5 Frank Sweetser
Multiple post options may be specified by repeating the -d argument.
99
<pre>
100
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
101
</pre>
102
103
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.)
104
105
<pre>
106
curl -d 'syslinux_config=Hello World' http://localhost:8443/tftp/00:11:22:33:44:55
107
</pre>
108
109
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.
110
111
<pre>
112 1 Ohad Levy
curl -X DELETE http://localhost:8443/tftp/00:11:22:33:44:55
113
</pre>
114 16 Corey Osman
115
h2. BMC Controls 
116
117
Summary
118
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.  
119
120
h3. Prerequisites
121
122
In order to control the BMC device using the smart proxy you must perform the following actions:
123
124
1. Enable bmc support in the settings.yml file
125
2. Install rubyipmi gem, 
126
3. Install freeipmi, and/or ipmitool either from source or package
127
4. The bmc device must be setup on the network with login credentials
128
5. Smart proxy must be able to reach the bmc device through the network
129
130
h3. Using Parameters with the BMC API
131
132
1. When using the bmc api, you must send the credentials of the bmc device using Http Basic Authorization
133
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
134
3. Some api calls have optional parameters, leaving the action blank on some api calls will return valid actions and options.
135
136 17 Corey Osman
h3. BMC Security
137 16 Corey Osman
138
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.
139
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 
140
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
141
by any other user.
142 6 Brian Gupta
143 23 Corey Osman
h3. Examples
144
145
returns boolean if the power is off  (Note this only occurs when using GET
146
<pre>
147
curl -vks --data 'bmc_provider=freeipmi' 'http://127.0.0.1:8443/bmc/192.168.1.16/chassis/power/off' -X GET -u admin:password  => {"action":"off","result":true}
148
</pre>
149
150
returns status when the power is turned off  (Note this only occurs when using PUT)
151
<pre>
152 34 Alexander Charykov
curl -vks --cacert /var/lib/puppet/ssl/certs/ca.pem --cert /var/lib/puppet/ssl/certs/`hostname -f`.pem --key /var/lib/puppet/ssl/private_keys/`hostname -f`.pem \
153 35 Alexander Charykov
     --data 'bmc_provider=freeipmi' 'https://127.0.0.1:8443/bmc/192.168.1.16/chassis/power/off' -X PUT -u admin:password  => {"action":"off","result":"192.168.1.16: ok\n"}
154 23 Corey Osman
</pre>
155
156
if you can't remember the basic bmc api actions you just leave things blank and the proxy will try to help you out.
157
<pre>
158
curl -vks --data 'bmc_provider=freeipmi' 'http://127.0.0.1:8443/bmc/192.168.1.16/chassis' -X GET -u admin:password => {"actions":["power","identify","config"]}
159
</pre>
160
161 24 Corey Osman
h4. Troubleshooting
162 28 Corey Osman
163 27 Corey Osman
In these examples you will notice that I have turned off SSL which you should never do in a production environment, but this is a short lived development machine.
164 29 Corey Osman
If you have some weird BMC issue you can have a look at the log if your using the latest smart proxy >= 1.9.  Starting with Rubyipmi 0.9.0 it will now generate a log with all the commands and responses it runs.
165 24 Corey Osman
<pre>
166
curl -vks --data 'bmc_provider=freeipmi' 'http://127.0.0.1:8443/bmc/192.168.1.16/chassis/power/off' -X GET -u admin:password  => {"action":"off","result":true}
167
D, [2015-03-10T16:12:57.328430 #68510] DEBUG -- : /usr/local/sbin/ipmipower --hostname=192.168.1.16   --stat --config-file=/var/folders/h6/v6nv76td37s7vqj902_z59kh0000gn/T/20150310-68510-w3rw89
168
D, [2015-03-10T16:12:57.694174 #68510] DEBUG -- : "/usr/local/sbin/ipmipower --hostname=192.168.1.16   --stat --config-file=/var/folders/h6/v6nv76td37s7vqj902_z59kh0000gn/T/20150310-68510-w3rw89 --driver-type=LAN_2_0"
169
D, [2015-03-10T16:12:57.694256 #68510] DEBUG -- : 192.168.1.16: off
170
</pre>
171
172 27 Corey Osman
If you just want to test your connection to see if your BMC device works with the provided information you can now use one of the new API commands named "test".  What this is doing in the background is running a bmc info command and if that
173
command fails it returns false.  You can view the logs to see why it failed. In a later release we will detail what caused the test to fail.
174 24 Corey Osman
<pre>
175 27 Corey Osman
# good password
176
curl -vks --data 'bmc_provider=freeipmi' 'http://127.0.0.1:8443/bmc/192.168.1.16/test' -X GET -u admin:password
177
{"action":"test","result":true}
178
#  bad password
179
curl -vks --data 'bmc_provider=freeipmi' 'http://127.0.0.1:8443/bmc/192.168.1.16/test' -X GET -u admin:bad_password
180
{"action":"test","result":false}
181 30 Corey Osman
D, [2015-03-20T10:04:25.288696 #92467] DEBUG -- : /usr/local/sbin/bmc-info --hostname=192.168.1.16   --config-file=/var/folders/h6/v6nv76td37s7vqj902_z59kh0000gn/T/20150320-92467-1og0ucl
182
D, [2015-03-20T10:04:25.335628 #92467] DEBUG -- : "/usr/local/sbin/bmc-info --hostname=192.168.1.16   --config-file=/var/folders/h6/v6nv76td37s7vqj902_z59kh0000gn/T/20150320-92467-1og0ucl --driver-type=LAN_2_0"
183
D, [2015-03-20T10:04:25.335706 #92467] DEBUG -- : /usr/local/sbin/bmc-info: password invalid
184
185 24 Corey Osman
</pre>
186
187 31 Corey Osman
How to provide additional options in the body
188
<pre>
189 32 Corey Osman
curl -vks --header "Content-Type: application/json" -d '{"bmc_provider":"freeipmi", "options":{"driver":"lan20", "privilege":"USER"}}' 'http://127.0.0.1:8443/bmc/192.168.1.21/chassis/power/off' -X GET -u admin:password
190 31 Corey Osman
</pre>
191
192 6 Brian Gupta
[[Draft 2.0 version of DNS API]]
193 21 Stephen Benjamin
194
h3. Realm API
195
196
Draft design: http://projects.theforeman.org/projects/foreman/wiki/RealmJoinIntegration
197
198
h4. New Host
199
200
The FreeIPA returns the raw XMLRPC JSON when creating a host, however the only relevant key is "randompassword."  Any other Realm providers at a minimum should return an OTP for a new host.
201
202
Example full output from FreeIPA:
203
204
<pre>
205
{
206
  "dn": "fqdn=hostname.example.com,cn=computers,cn=accounts,dc=example,dc=com", 
207
  "fqdn": [
208
    "hostname.example.com" 
209
  ], 
210
  "has_keytab": false, 
211
  "has_password": true, 
212
  "ipauniqueid": [
213
    "5f5d467c-9fce-11e3-bcca-525400d17cb3" 
214
  ], 
215
  "managedby_host": [
216
    "hostname.example.com" 
217
  ], 
218
  "objectclass": [
219
    "ipaSshGroupOfPubKeys", 
220
    "ipaobject", 
221
    "ieee802device", 
222
    "nshost", 
223
    "top", 
224
    "ipaservice", 
225
    "pkiuser", 
226
    "ipahost", 
227
    "ipasshhost" 
228
  ], 
229
  "randompassword": "_i7@PhgpAnjn" 
230
}
231
</pre>
232
233
h4. Update Host
234
235
* "rebuild=true" is passed for any host being rebuilt in order to know whether to revoke any outstanding certificates, etc.  A new randompassword should be issued.
236
237
* Foreman also triggers an update if the "userclass" is being updated.  You should not return a new one-time password for this, only update the attribute (if desired) and return 200.  If nothing needs to be updated, you should return resposen 200 and this JSON
238
239
<pre>
240
{"message" => "nothing to do"}
241
</pre>
242
243
h4. Delete a host
244
245
The Smart Proxy will return 404 if not found, 400 for any other error.