Document toolboxDocument toolbox

Manage relay rules using the API

Owned by Juan Tomás Alonso Nieto (Deactivated)
Last updated: Dec 20, 2023 by Borja Moro Moreno
8 min read
[ 1 Overview ] [ 2 Endpoints and methods ]

Overview

Check the list of available endpoints and methods to manage the rules assigned to your relays:

Endpoints and methods

Description

Endpoints and methods

Description

GET /relays/{name}/rules see below

Get the list of rules defined for a specific relay.

post /relays/{name}/rules see below

Add new rules to a relay.

PUT /relays/{name}/rules see below

Edit a rule of a relay.

DELETE /relays/{name}/rules see below

Delete a rule of a relay.

Endpoints and methods

GET /relays/{name}/rules

Get the list of rules defined for a specific relay.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

Parameter

Type

Description

name required

string

Enter the name of the relay that contains the rules you want to retrieve.

Find below a request example:

https://api-us.devo.com/maduro/relays/myRelay/rules

Code

Description

Message

Code

Description

Message

200

Successful response. Relay rules information retrieved.

[ { "order": 1, "name": "firewall rule", "description": "a rule for firewalls", "creationDate": "2014-05-24T20:38:00Z", "updateDate": "2022-05-28T21:00:00Z", "source": { "port": 13004, "ip": "127.0.0.1", "tag": "my.firewall.tag", "hostname": "local.cisco-10", "message": "login failed", "data": "login failed", "hasSyslogTag": true, "tcpThreads": 1, "tcpReceiveBuffer": 256, "udpThreads": 1, "udpReceiveBuffer": 256, "maxPacketSize": 4096, "level": null, "facility": null }, "target": { "tag": "my.firewall.tag", "tagIsPrefix": false, "message": "login failed", "stopProcessing": false, "drop": false } } ]

400

Bad request. The specific error will be shown in the message.

{ "error": { "code": 12, "message": "Invalid signature validation" } }

403

Forbidden request.

404

Relay not found.

405

Method not allowed.

POST /relays/{name}/rules

Add new rules to a relay.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

Parameter

Type

Description

name required

string

Enter the name of the relay to which you want to add rules.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Description

Parameter

Type

Description

override

boolean

If set to true, the new rules will replace the existing ones. Otherwise, they will be appended to the end of the rule list.

The default value is false.

Request body

The request JSON body must include an object with the following key-value pairs:

One JSON object per rule

You must add a JSON object per each rule you need to define.

Parameter

Type

Description

Parameter

Type

Description

name required

string

Enter the name of the new rule.

description

string

Add an optional description for the relay rule. The default value is null.

source required

object

The source object must contain the following values:

  • port required (integer) - The rule will be applied to events received at this port on the relay.

  • ip required (string) - The rule will be applied to data originating from this IP address. The default value is null.

  • tag required (string) - This refers to the $syslogtag$ information contained in the source event. The default value is null.

  • hostname required (string) - The rule will be applied to data originating from this hostname. The default value is null.

  • message required (string) - This refers to the $msg$ information contained in the source event. The default value is null.

  • data required (string) - This represents the combination of the $syslogtag$ and $msg$ information. The default value is null.

  • hasSyslogTag required (boolean) - Set this to true if the data source will send events to the relay with a syslog tag component. The default value is true.

  • tcpThreads required (integer) - Number of threads used by the TCP port. The default value is 1.

  • tcpReceiveBuffer required (integer) - TCP receiver socket buffer size in bytes. The default value is 0.

  • udpThreads required (integer) - Number of threads used by the UDP port. The default value is 1.

  • udpReceiveBuffer required (integer) - UDP receiver socket buffer size in bytes. The default value is 0.

  • maxPacketSize required (integer) - Maximum packet size in bytes for transmission over UDP. The default value is 4096.

  • level required (string) - The rule will only be applied to the events that are received with the syslog level you indicate here. Must be one of the following (the default value is null):

    • EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG

  • facility required (string) - The rule will only be applied to the events that are received with the syslog facility you indicate here. Must be one of the following (the default value is null):

    • KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP, CRON, AUTHPRIV, FTP, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7

target required

object

The target object must contain the following values:

  • tag required (string) - This is the Devo tag to be applied to events that meet the conditions of this rule. The default value is null.

  • tagIsPrefix required (boolean) - Set this value to true if you want to retain the original syslog (source) tag received and append it to the target tag. The default value is false.

  • message required (string) - This defines the content of the syslog $msg$ component that the relay will forward to Devo. The default value is null.

  • stopProcessing required (boolean) - Set this value to true if you want events that match this rule to undergo no further processing, that is, no subsequent rules should be applied after this rule. The default value is false.

  • drop required (boolean) - Set this value to true if you want to drop events that meet the conditions of this rule. The default value is false.

Find below a request example:

Code

Description

Message

Code

Description

Message

201

Successful response. New rule(s) created.

-

400

Bad request. The specific error will be shown in the message.

403

Forbidden request.

405

Method not allowed.

PUT /relays/{name}/rules

Edit a rule of a relay.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

Parameter

Type

Description

name required

string

Enter the name of the relay that contains the rules you want to edit.

Request body

The request JSON body must include an object with the following key-value pairs:

Parameter

Type

Description

Parameter

Type

Description

name required

string

Enter the name of the rule you want to edit.

description

string

Add an optional description for the relay rule. The default value is null.

source required

object

The source object must contain the following values:

  • port required (integer) - The rule will be applied to events received at this port on the relay.

  • ip required (string) - The rule will be applied to data originating from this IP address. The default value is null.

  • tag required (string) - This refers to the $syslogtag$ information contained in the source event. The default value is null.

  • hostname required (string) - The rule will be applied to data originating from this hostname.

  • message required (string) - This refers to the $msg$ information contained in the source event. The default value is null.

  • data required (string) - This represents the combination of the $syslogtag$ and $msg$ information. The default value is null.

  • hasSyslogTag required (boolean) - Set this to true if the data source will send events to the relay with a syslog tag component. The default value is true.

  • tcpThreads required (integer) - Number of threads used by the TCP port. The default value is 1.

  • tcpReceiveBuffer required (integer) - TCP receiver socket buffer size in bytes. The default value is 0.

  • udpThreads required (integer) - Number of threads used by the UDP port. The default value is 1.

  • udpReceiveBuffer required (integer) - UDP receiver socket buffer size in bytes. The default value is 0.

  • maxPacketSize required (integer) - Maximum packet size in bytes for transmission over UDP. The default value is 4096.

  • level required (string) - The rule will only be applied to the events that are received with the syslog level you indicate here. Must be one of the following (the default value is null):

    • EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG

  • facility required (string) - The rule will only be applied to the events that are received with the syslog facility you indicate here. Must be one of the following (the default value is null):

    • KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP, CRON, AUTHPRIV, FTP, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7

target required

object

The target object must contain the following values:

  • tag required (string) - This is the Devo tag to be applied to events that meet the conditions of this rule. The default value is null.

  • tagIsPrefix required (boolean) - Set this value to true if you want to retain the original syslog (source) tag received and append it to the target tag. The default value is false.

  • message required (string) - This defines the content of the syslog $msg$ component that the relay will forward to Devo. The default value is null.

  • stopProcessing required (boolean) - Set this value to true if you want events that match this rule to undergo no further processing, that is, no subsequent rules should be applied after this rule. The default value is false.

  • drop required (boolean) - Set this value to true if you want to drop events that meet the conditions of this rule. The default value is false.

Find below a request example:

DELETE /relays/{name}/rules

Delete a rule of a relay.

Â