AMQP API

Summary

A request always has the following structure:

{
    "action": <action_type>,
    "collection": <collection_name>,
    "id": <id>,
    "attributes": {
        <key1>: <value1>,
        <key2>: <value2>,
        <key3>: <value3>
        },
    "filters": {
        <filter1>: <value1>,
        <filter2>: <value2>,
        <filter3>: <value3>
        },
}

• action and collection are mandatory
• For a read action, if the id is not specified, the request will get a list of resources available in the collection.

Here's an example of renaming a group name student to students:

1. Go to section "Groups" of this. It will be the collection_name
2. Pick the right action, update
3. Id is mandatory, it's the group name.
4. Fill the attributes section. The key is new_name. Set it to students

{
    "collection": "groups",
    "action": "update",
    "id": "student",
    "attributes": {
        "new_name": "students"
    }
}

Filters

Filters can be applied to any request. You can filter by:

• Uuid: uuids
• Hostname: hostnames (matches wildcards)
• IP Address: ip_addresses
• MAC Address: mac_addresses

Example:

{
    "collection": "hosts",
    "action": "read",
    "filters": {"hostnames": ["*.guardis.be", "*.guardis.com"]}
}

Collection: hosts

read

Retrieves informations about a group.

• id: The group name.
• attributes: A list of informations to retrieve.

Available informations are:

• hostname
• mac or mac_addresses
• memtotal
• ip
• uptime
• platform

Collection: executables

update

Execute command on remote hosts.

• id (mandatory): The command.
• attributes: None

Collection: groups

read

Retrieves informations about a group.

• id: The group name.
• attributes: None

create

Creates a group with the given name

• id (mandatory): The group name
• attributes: None

update

Changes a group name.

• id (mandatory): The group name
• attributes:
  • new_name: The new name

delete

Deletes a group.

• id (mandatory): The group name
• attributes: None

Collection: users

read

Gets information about user.

• id: The user name.
• attributes: None

create

Creates a user.

• id (mandatory): The user name.
• attributes:
  • password: The user's password (clear text)
  • login_group: The user's main group
  • groups: Additionnal groups of the user (comma separated string)

update

Updates a user.

• id (mandatory): The user name.
• attributes:
  • password: The user's password (clear text)
  • login_group: The user's main group
  • add_to_groups: Add user to these groups(comma separated string)
  • remove_from_groups: Remove user from these groups(comma separated string)
  • set_groups: Resets then sets groups for user

delete

Deletes a user with the force flag.

• id (mandatory): The user name
• attributes: None

Collection: packages

read

Gets the status installation of a package. Installed or not.

• id: The package name.
• attributes: None

create

Installs a package.

• id (mandatory): The package name.
• attributes: None

update

Updates a package.

• id: The package name. If not specified, it will update all packages
• attributes: None

delete

Removes a package.

• id (mandatory): The package name.
• attributes: None

Collection: services

read

Retrieves the status of a service. (running, enabled)

• id (mandatory): The service name.
• attributes: None

update

Enable/disable and starts/stop a serevice

• id (mandatory): The service name.
• attributes:
  • enabled: True/False
  • running: True/False

Collection: files

read

Retrieves the owner, group, and mode of a file.

• id: The file name.
• attributes:
  • get_content: (boolean) Additionnaly retrieves the file content
  • md5: (boolean) Calculates the file's md5sum

create or update

Creates a file. Sets the owner, group, mode, and content of a file.

• id: The file name.
• attributes:
  • owner: Sets the file owner (the user must exist)
  • group: Sets the file group (the group must exist)
  • mode: Sets the file mode
  • content: (string) The file content as a string
  • content_by_url: (url) Fetch the content from this url
  • encoding: Currently supported (None/base64)

delete

Deletes a file

• id: The file name.
• attributes: None

Collection: repos

read

Retrieves all package repositories defined if id isn't provided. Retrieves a repo details if id is provided.

• id: The repo name
• attributes:
  • details: (boolean) Additionnaly retrieves repositories details when no id is specified. Only the names if set to false.

create or update

Creates or updates a repo. Here, only mandatory attributes are shown.

• id: The repo name.
• attributes:
  • baseurl: (string) The base url for the repo.

On Debian, entries follow this minimal format. One file per repository will be created in /etc/apt/sources.list.d. The filename will be <id>.list.

deb http://site.example.com/debian distribution component1 component2 component3

On debian, you can group the baseurl, distribution and components, or specify them separately:

• distribution: (string) See Debian example below.
• components: (list or comma separated values) See Debian example below.

{
 'attributes': {'baseurl': 'http://dl.comodit.com/pub debian-squeeze test test2 test3'},
}

is equivalent to

{
 'attributes': {'baseurl': 'http://dl.comodit.com/pub',
                'distribution': 'debian-squeeze',
                'components': ['test', 'test2', 'test3']},
}

is equivalent to

{
 'attributes': {'baseurl': 'http://dl.comodit.com/pub',
                'distribution': 'debian-squeeze',
                'components': 'test, test2, test3'},
}

On RedHat, entries follow this minimal format. Every other option defined in the yum.conf manpage (enabled, gpgcheck, etc) is available though.

[synapse-dev]
baseurl=http://danube.comodit.net/repo/fedora/16/i386/

delete

Deletes the repo.

• id: The repo name.