API¶

Foreman Smart Proxy provides a REST API, communicating via JSON.

Please refer to this document for latest information about Foreman Smart Proxy API.

The API entries containing variant are only available in smart-proxy v2.0 and later.

List of API's¶

Path	REST Type	Description	Example Input JSON
FEATURES
/features	GET	List of features supported by the proxy
/version	GET	Proxy version
DHCP
/dhcp	GET	Retrieve a list of subnets
/dhcp/10.1.2.0	GET	Retrieve 10.1.2.0 subnets records
/dhcp/10.1.2.0/10.1.2.5	GET	Retrieve 10.1.2.5 reservation information
/dhcp/10.1.2.0/unused_ip	GET	Provides an unused ip address in 10.1.2.0 subnet
/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}
/dhcp/10.1.2.0/10.1.2.5	DELETE	Deletes 10.1.2.5 reservation from 10.1.2.0 subnet
DNS
/dns/	POST	Create a new DNS record	{"fqdn":string(name/ip), "value":string(ip/reverse), "type":string(A/PTR)}
/dns/value	DELETE	remove value(ip or reverse) DNS record
TFTP
/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"
/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"
/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"
/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"
/tftp/create_default	POST	creates a default pxelinux configuration file	{"syslinux_config":string}. Implicit variant of "syslinux"
/tftp/<variant>/create_default	POST	creates a default pxeconfig configuration file	{"pxeconfig":string}. Variant can be "syslinux" or "pxegrub"
/tftp/fetch_boot_file	POST	creates a default pxelinux configuration file	{"prefix":string, "path":string}
/tftp/serverName	GET	fetches the TFTP server name to be used within a dhcp record
PUPPET CA
/puppet/ca	GET	list of all puppet certificates
/puppet/ca/certname	POST	Sign pending certificate request
/puppet/ca/certname	DELETE	Remove (clean) and revoke a certificate
/puppet/ca/autosign	GET	list of all puppet autosign entires
/puppet/ca/autosign/certname	POST	Add certname to Puppet autosign
/puppet/ca/autosign/certname	DELETE	Remove certname from Puppet autosign
PUPPET
/puppet/run	POST	Trigger puppet run / kick	["hostA", "hostB"]
/puppet/environments	GET	list of all puppet environment names
/puppet/environments/production>	GET	show puppet production environment name and module paths
/puppet/environments/production/classes	GET	return a hash of puppet classes in the production environment	Puppet class parameters is supported from 1.1

Please raise a new issue if you need additional API's

Manually Calling the API¶

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.

curl http://localhost:8443/features

The results can also be returned as JSON if you set an appropriate Accept header.

curl -H "Accept: application/json" http://localhost:8443/features

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.

curl -d 'nodes=server.example.com' http://localhost:8443/puppet/run

This curl command line will add an A record for server.example.com with ip address of 10.1.2.5.

curl -d 'fqdn=servers.example.com&value=10.1.2.5&type=A' http://localhost:8443/dns/

Multiple post options may be specified by repeating the -d argument.

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

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.)

curl -d 'syslinux_config=Hello World' http://localhost:8443/tftp/00:11:22:33:44:55

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.

curl -X DELETE http://localhost:8443/tftp/00:11:22:33:44:55

Draft 2.0 version of DNS API