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: Nona

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: hypervisors

read

Returns the managed hypervisors, the virtual machines on a given hypervisor or information about a virtual machine.

The id attribute is the hypervisor's id. Those ids are specified in a configuration file ('/etc/synapse/hypervisors.conf').

If none of the hypervisor's id or the virtual machine's name is given, then the response will contain a list of the managed hypervisors ids.

• id: The hypervisor's name.
• attributes:
  • name: The virtual machine name on the specified hypervisor. If the name of the virtual machine is not specified, then it returns the defined virtual machines on the specified hypervisor.

create

Creates and provisions a virtual machine.

• id (mandatory): The hypervisor's name.
• attributes:
  • name (mandatory)(string): vm name.
  • type (mandatory)(string): hypervisor type.
  • memory (mandatory)(integer): domain memory.
  • kernel_path (mandatory)(string): path to the vmlinuz file on the local machine where synapse runs. It can also be an URL. In this case, the file is downloaded to the /tmp/ directory
  • initrd_path (mandatory)(string): same as vmlinuz but for initrd.img
  • num_cpu (integer): number of CPU. Default: 1.
  • arch_type (string): CPU architecture. Default: i686.
  • cmd_line (string): kernel parameters like "ks=<path_to_kickstart_file>". Default: "".
  • boot_dev (string): boot device. Default: "hd".
  • disk_driver (string): disk driver name ("tap", "tap2", "phy", or "file" for xen and "qemu" for qemu). Default: "qemu".
  • disk_type (string): disk type ("aio" for xen and "raw", "bochs", "qcow2", or "qed" for qemu). Default: "raw"
  • disk_size_unit (string): unit of disk size. Default: "M".
    • "B", "bytes" or undefined for bytes
    • "K", "KB" or "KiB" for kilobytes
    • "M", "MB" or "MiB" for megabytes
    • "G", "GB" or "GiB" for gigabytes
    • "T", "TB" or "TiB" for terabytes).
  • disk_size (integer): disk size. Default: 3072.
  • bridged (boolean): tells if the domain is bridged to an interface. Default: true
  • bridge_mac_address (string): MAC address for the bridge interface. Automatically generated when no specified.
  • bridge_interface (string): interface of the bridge. Default: "br0".
  • vnc_port (integer): port for VNC display. Default: -1 (auto)
  • storage_name (string): storage name. Default: generated

update

Update domain settings.

• id (mandatory): The hypervisor's name.
• attributes:
  • name (mandatory)(string): The virtual machine name on the specified hypervisor.
  • status (string): domain status after update. It can be "running", "paused", "shutdown", "shutoff" or "rebooting".
  • disk_size (integer): disk size
  • disk_size_unit (string): unit of disk size
  • memory (integer): memory size in kilobytes
  • num_cpu (integer): number of CPU

delete

Delete a domain and even it's storage if specified.

• id (mandatory): The hypervisor's name.
• attributes:
  • name (mandatory)(string): The virtual machine name on the specified hypervisor.
  • delete_volumes (boolean): tells if the disk volume has to be removed too