REST API

Table of Contents

Default setup
Status
Promises regeneration
Dynamic groups regeneration
Technique library reload
Archives manipulation

Rudder can be used as a web service using a REST API.

This documentation covers the version 1 of Rudder's API, that has been present since Rudder 2.4.

The version 2 has now been implemented, which is much more complete, in Rudder 2.7, and has a dedicated documentation available here: http://www.rudder-project.org/rudder-api-doc/

[Warning]Warning

The version 1 is to be considered legacy and should not be used anymore. Please migrate to version 2 to benefit from the new authentication features and more complete existing methods.

Default setup

Access to REST API can be either using Rudder authentication, either unauthenticated, using authentication mechanisms set elsewhere, for instance at Apache level.

Rudder Authentication

By default, the access to the REST API is open to users not authenticated in Rudder.

The method of authentication can be configured in /opt/rudder/etc/rudder-web.properties

rudder.rest.allowNonAuthenticatedUser=true

Apache access rules

By default, the REST API is exposed for localhost only, at http://localhost/rudder/api.

Example 9. Example usage of non authenticated REST API

Unrestricted access can be granted to local scripts accessing to localhost, whereas remote access to the REST API will be either denied, or restricted through authentication at apache level.



User for REST actions

Actions done using the REST API are logged by default as run by the user UnknownRestUser.

To change the name of this user, add following header to the HTTP request:

X-REST-USERNAME: MyConfiguredRestUser

If the REST API is authenticated, the authenticated user name will be used in the logs.

Status

http://localhost/rudder/api/status
Check if Rudder server is up and return OK. If Rudder server is not responding, an error is displayed.

Promises regeneration

http://localhost/rudder/api/deploy/reload
Regenerate promises (same action as the Regenerate now button).

Dynamic groups regeneration

http://localhost/rudder/api/dyngroup/reload
Check all dynamic groups for changes. If changes have occurred, regenerate the groups in the LDAP and the CFEngine promises.

Technique library reload

http://localhost/rudder/api/techniqueLibrary/reload
Check the technique library for changes. If changes have occurred, reload the technique library in memory and regenerate the CFEngine promises.

Archives manipulation

Various methods are available to import and export items:

Archiving:

http://localhost/rudder/api/archives/archive/groups
Export node groups and node groups categories.
http://localhost/rudder/api/archives/archive/directives
Export policy library (categories, active techniques, directives).
http://localhost/rudder/api/archives/archive/rules
Export rules
http://localhost/rudder/api/archives/archive/full
Export everything

Listing:

http://localhost/rudder/api/archives/list/groups
List available archives datetime for groups (the datetime is in the format awaited for restoration).
http://localhost/rudder/api/archives/list/directives
List available archives datetime for policy library (the datetime is in the format awaited for restoration).
http://localhost/rudder/api/archives/list/rules
List available archives datetime for configuration rules (the datetime is in the format awaited for restoration).
http://localhost/rudder/api/archives/list/full
List available archives datetime for full archives (the datetime is in the format awaited for restoration).

Restoring a given archive:

http://localhost/rudder/api/archives/restore/groups/datetime/[archiveId]
Restore given groups archive.
http://localhost/rudder/api/archives/restore/directives/datetime/[archiveId]
Restore given directives archive.
http://localhost/rudder/api/archives/restore/rules/datetime/[archiveId]
Restore given rules archive.
http://localhost/rudder/api/archives/restore/full/datetime/[archiveId]
Restore everything.

Restoring the latest available archive (from a previously archived action, and so from a Git tag):

http://localhost/rudder/api/archives/restore/groups/latestArchive
http://localhost/rudder/api/archives/restore/directives/latestArchive
http://localhost/rudder/api/archives/restore/rules/latestArchive
http://localhost/rudder/api/archives/restore/full/latestArchive

Restoring the latest available commit (use Git HEAD):

http://localhost/rudder/api/archives/restore/groups/latestCommit
http://localhost/rudder/api/archives/restore/directives/latestCommit
http://localhost/rudder/api/archives/restore/rules/latestCommit
http://localhost/rudder/api/archives/restore/full/latestCommit

Downloading a ZIP archive

The REST API allows to download a ZIP archive of groups, directives and rules (as XML files) for a given Git commit ID (the commit HASH).

It is not designed to query for available Git commit ID, so you will need to get it directly from a Git tool (for example with Git log) or from the list API.

Note that that API allows to download ANY Git commit ID as a ZIP archive, not only the one corresponding to Rudder archives.

Note 2: you should rename the resulting file with a ".zip" extension as most zip utilities won’t work correctly on a file not having it.

http://localhost/rudder/api/archives/zip/groups/[GitCommitId]
Download groups for the given Commit ID as a ZIP archive.
http://localhost/rudder/api/archives/zip/directives/[GitCommitId]
Download directives for the given Commit ID as a ZIP archive.
http://localhost/rudder/api/archives/zip/rules/[archiveId]
Download rules for the given Commit ID as a ZIP archive.
http://localhost/rudder/api/archives/zip/all/[archiveId]
Download groups, directives and rules for the given Commit ID as a ZIP archive.
Prev Up Next
Basic administration of Rudder services Home User management