This section contains sample templates that illustrate the following:
- Session management using login and logout templates
- Viewing event types
- XML parsing and handling
- Steps execution through backtracking and loops in a template
- Operations using namespace variables
- IP-related XC operations
- WAPI integration
...
Note: Some of the templates are specific for Rapid7 servers.
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
Following is a sample session management template for REST API endpoint:
{ "name": "session",
"version": "2.0",
"type": "REST_ENDPOINT",
"vendor_identifier": "Rapid7",
"path": "/api/1.1/xml",
"keepalive": true,
"login_template": "login",
"logout_template": "logout",
"session_duration": 60000 }
...
Note: The The login_template and logout_template lines specify the templates to be executed for login and logout.
The session_duration line specifies the length of the session. You must upload the login and logout templates and logout templates before configuring a session management template that refers them.
...
Wiki Markup
{"name":
...
"
...
session_tmplate",
...
"version":
...
"
...
3.0",
...
"
...
type":
...
"
...
DXL_ENDPOINT",
...
"
...
vendor_identifier":
...
"
...
DXL",
...
"dxl_keep_alive_interval": 60,"dxl_topic": "/outbound/session"}
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
{
"name": "login",
"version": "2.0",
"vendor_identifier": "Rapid7",
"type": "REST_EVENT",
"event_type": ["SESSION"],
"content_type": "text/xml",
"quoting": "XMLA",
"steps": [
{
"body": "${XC:ASSIGN:{H:Authorization}:{S:}}",
"operation": "NOP",
"name": "login: clear basic auth"
},
{
"parse": "XMLA",
"operation": "POST",
"no_connection_debug":
...
false,
...
"name":
...
"login:
...
request",
...
"body_list":
...
[
...
"<?xml
...
version=\"1.0\"
...
encoding=\"UTF-8\"?>",
...
"<LoginRequest
...
user-id=\"$
...
{UT::USERNAME
...
}\"
...
password=\"$
...
{UT::PASSWORD
...
}\"/>"
...
]
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"login:
...
errorcheck",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{P:A:PARSE
...
[
...
[name
...
]
...
]
...
}",
...
"left":
...
"LoginResponse"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"1",
...
"left":
...
"$
...
{P:A:PARSE
...
{
...
{success
...
}
...
}
...
}"
...
}
],
...
"condition_type":
...
"OR",
...
"else_eval":
...
"$
...
{XC:COPY:
...
{S:SESSID
...
}:
...
{P:PARSE
...
{
...
{session-id
...
}
...
}
...
}
...
}",
...
"error":
...
true
...
}
}
]
}
...
Note: The else_eval line copies the session-id from the parsed reply (if successful); otherwise, it returns an error.
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
...
{
"name":
...
"logout",
...
"version":
...
"2.0",
...
"type":
...
"REST_EVENT",
...
"vendor_identifier":
...
"Rapid7",
...
"event_type":
...
["SESSION"
...
],
...
"content_type":
...
"text/xml",
...
"quoting":
...
"XMLA",
...
"steps":
...
[
...
{
"parse":
...
"XMLA",
...
"operation":
...
"POST",
...
"no_connection_debug":
...
false,
...
"name":
...
"logout:
...
request",
...
"body_list":
...
[
...
"<?xml
...
version=\"1.0\"
...
encoding=\"UTF-8\"?>",
...
"<LogoutRequest
...
session-id=\"$
...
{S::SESSID
...
}\"/>"
...
]
},
{
"operation":
...
"CONDITION",
...
"name":
...
"logout:
...
errorcheck",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{P:A:PARSE
...
[
...
[name
...
]
...
]
...
}",
...
"left":
...
"LogoutResponse"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"1",
...
"left":
...
"$
...
{P:A:PARSE
...
{
...
{success
...
}
...
}
...
}"
...
}
],
...
"condition_type":
...
"OR",
...
"error":
...
true
...
}
}
]
}
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
Wiki Markup
{ "vendor_identifier": "DXL", "version":
...
"
...
3.0",
...
"
...
name":
...
"
...
action
...
", "type":
...
"
...
DXL_EVENT",
...
"event_type":
...
[
...
"FIXED_ADDRESS_IPV4" ],
...
"
...
dxl_topic": "/outbound/action", "steps":
...
[
...
{
...
"
...
operation":
...
"DXL_SEND_EVENT",
...
"
...
name":
...
"
...
send_ip",
...
"
...
body":
...
"address ${E:A:
...
values{ipv4addr}}",
...
"
...
dxl_topic":
...
"
...
/outbound/step"
}
]
}
Following is a sample action template for REST API endpoint:
{
"name": "action",
"vendor_identifier": "Rapid7",
"version": "2.0",
"content_type": "text/xml",
"action_type": "add network or remove IP",
"quoting": "XMLA",
"type": "REST_EVENT",
"event_type": [ "FIXED_ADDRESS_IPV4", "FIXED_ADDRESS_IPV6" ],
"steps": [
{
"name": "check operation type",
"operation": "CONDITION",
"condition": {
"statements": [
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "INSERT"
},
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "DELETE"
}
],
"condition_type": "AND",
"stop": true
}
},
{
"name": "send SiteListingRequest",
"operation": "POST",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteListingRequest session-id=\"${S::SESSID}\" />"
],
"parse": "XMLA"
},
{
"operation": "CONDITION",
"name": "send SiteListingRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${P:A:PARSE[[name]]}",
"left": "SiteListingResponse"
},
{
"op": "!=",
"right": "1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true,
"else_eval": "${XC:COPY:{L:site_list}:{P:PARSE}"
}
},
{
"operation": "CONDITION",
"name": "check whether site list is empty",
"condition": {
"statements": [{
"op": "==",
"right": "${L:L:site_list}",
"left": "0"
}],
"condition_type": "AND",
"stop": true
}
},
{
"operation": "VARIABLEOP",
"name": "get the next site",
"variable_ops": [{
"operation": "POP",
"type": "COMPOSITE",
"destination": "L:a_site",
"source": "L:site_list"
}]
},
{
"operation": "CONDITION",
"name": "check site name",
"condition": {
"statements": [{
"op": "!=",
"right": "${L:A:a_site{{name}}}",
"left": "${E:A:values{extattrs}{r7_site}{value}}"
}],
"condition_type": "AND",
"next": "check whether site list is empty",
"else_eval": "${XC:COPY:{L:site_id}:{L:a_site{{id}}}}"
}
},
{
"parse": "XMLA",
"operation": "POST",
"name": "send SiteConfigRequest",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteConfigRequest session-id=\"${S::SESSID}\" site-id=\"${L:A:site_id}\"/>"
]
},
{
"operation": "CONDITION",
"name": "send SiteConfigRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${P:A:PARSE[[name]]}",
"left": "SiteConfigResponse"
},
{
"op": "!=",
"right": "1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"else_eval": "${XC:COPY:{L:Site}:{P:PARSE{SiteConfigResponse}}}",
"error": true
}
},
{
"operation": "CONDITION",
"name": "check operation type again",
"condition": {
"statements": [{
"op": "==",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"eval":
"${XC:COPY:{L:network}:{E:values{network}}}${XC:NETWORKTORANGE:{L:network}:{L:range
}}",
"next": "insert network"
}
},
{
"operation": "CONDITION",
"name": "remove ip",
"condition": {
"statements": [{
"op": "==",
"right": "${E:A:event_type}",
"left": "FIXED_ADDRESS_IPV4"
}],
"condition_type": "AND",
"eval":
"${XC:COPY:{L:ip}:{E:values{ipv4addr}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}",
"else_eval":
"${XC:COPY:{L:ip}:{E:values{ipv6addr}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
}
},
{
"operation": "CONDITION",
"name": "jump to send",
"condition": {
"statements": [{
"op": "==",
"right": "",
"left": ""
}],
"condition_type": "AND",
"next": "send SiteSaveRequest"
}
},
{
"operation": "VARIABLEOP",
"name": "insert network",
"variable_ops": [{
"operation": "PUSH",
"type": "COMPOSITE",
"source": "L:range",
"destination": "L:Site{Site}{Hosts}"
}]
},
{
"parse": "XMLA",
"operation": "POST",
"name": "send SiteSaveRequest",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
...
"<SiteSaveRequest
...
session-id=\"$
...
{S::SESSID
...
}\">",
...
"$
...
{L:x:Site
...
}",
...
"</SiteSaveRequest>"
...
]
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"send
...
SiteSaveRequest
...
(error
...
check)",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{P:A:PARSE
...
[
...
[name
...
]
...
]
...
}",
...
"left":
...
"SiteSaveResponse"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"1",
...
"left":
...
"$
...
{P:A:PARSE
...
{
...
{success
...
}
...
}
...
}"
...
}
],
...
"condition_type":
...
"OR",
...
"error":
...
true
...
}
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"check
...
operation
...
type
...
once
...
more",
...
"condition":
...
{
...
"statements":
...
[
...
{
...
"op":
...
"!=",
...
"right":
...
"$
...
{E:A:operation_type
...
}",
...
"left":
...
"INSERT"
...
}
...
],
...
"condition_type":
...
"AND",
...
"stop":
...
true
...
}
},
...
{
"operation":
...
"PUT",
...
"name":
...
"add
...
an
...
attribute
...
with
...
WAPI",
...
"transport":
...
{"path":
...
"$
...
{E:A:values
...
{_ref
...
}
...
}"
...
},
...
"wapi":
...
"v2.6",
...
"body":
...
"
...
{\"extattrs+\":
...
{\"r7_added\":
...
{\"value\":
...
\"Added
...
to
...
the
...
Rapid7
...
$
...
{UT:A:TIME
...
}\"
...
}
...
}
...
}"
...
}
]
}
Action Template: Check Operation Type
...
{
"name":
...
"check
...
operation
...
type",
...
"operation":
...
"CONDITION",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{E:A:operation_type
...
}",
...
"left":
...
"INSERT"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{E:A:operation_type
...
}",
...
"left":
...
"DELETE"
...
}
],
...
"condition_type":
...
"AND",
...
"stop":
...
true
...
}
...
Note: The "check operation type" step checks the operation type. If it is neither INSERT nor DELETE, the template execution stops.
...
Action Template: Get the List of Sites
...
{
"name":
...
"send
...
SiteListingRequest",
...
"operation":
...
"POST",
...
"body_list":
...
[
...
"<?xml
...
version=\"1.0\"
...
encoding=\"UTF-8\"?>",
...
"<SiteListingRequest
...
session-id=\"$
...
{S::SESSID
...
}\"
...
/>"
...
],
...
"parse":
...
"XMLA"
...
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"send
...
SiteListingRequest
...
(error
...
check)",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op": "!=",
"right": "${P:A:PARSE
...
[
...
[name
...
]
...
]
...
}",
...
"left":
...
"SiteListingResponse"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"1",
...
"left":
...
"$
...
{P:A:PARSE
...
{
...
{success
...
}
...
}
...
}"
...
}
],
...
"condition_type":
...
"OR",
...
"error":
...
true,
...
"else_eval":
...
"$
...
{XC:COPY:
...
{L:site_list
...
}:
...
{P:PARSE
...
}"
...
}
}
...
Note: The "send SiteListingRequest" and "send SiteListingRequest (error check)" steps request the list of sites on a Rapid7 server. If the response is successful, it copies the list to the L:site_list variable.
\\
\\
\\
...
Action Template: Locate the Site ID by Name
...
{
"operation":
...
"CONDITION",
...
"name":
...
"check
...
whether
...
site
...
list
...
is
...
empty",
...
"condition":
...
{
...
"statements":
...
[{
"op":
...
"==",
...
"right":
...
"$
...
{L:L:site_list
...
}",
...
"left":
...
"0"
...
}
...
],
...
"condition_type":
...
"AND",
...
"stop":
...
true
...
}
},
...
{
"operation":
...
"VARIABLEOP",
...
"name":
...
"get
...
the
...
next
...
site",
...
"variable_ops":
...
[
...
{
...
"operation":
...
"POP",
...
"type":
...
"COMPOSITE",
...
"destination":
...
"L:a_site",
...
"source":
...
"L:site_list"
...
}
...
]
...
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"check
...
site
...
name",
...
"condition":
...
{
...
"statements":
...
[
...
{
...
"op":
...
"!=",
...
"right":
...
"$
...
{L:A:a_site
...
{
...
{name
...
}
...
}
...
}",
...
"left":
...
"$
...
{E:A:values
...
{extattrs
...
}
...
{r7_site
...
}
...
{value
...
}
...
}"
...
}
...
],
...
"condition_type":
...
"AND",
...
"next":
...
"check
...
whether
...
site
...
list
...
is
...
empty",
...
"else_eval":
...
"$
...
{XC:COPY:
...
{L:site_id
...
}:
...
{L:a_site
...
{
...
{id
...
}
...
}
...
}
...
}"
...
}
}
NOTES:
- The "
check whether site list is empty", "get the next site", and "check site name" steps form a loop for finding the site with specific name in the list of sites. - The "
check whether site list is empty" step checks to see if the list is empty. If it is empty, the site with the specific name is not found and the execution of the template stops. - In the "
get the next site" step, one element is copied to theL:a_sitevariable. - In the "
check site name" step, the "name" attribute of a site (${L:A:a_site{{name}}}) is compared to the value of the "r7_site" extensible attribute of the fixed address in(${E:A:values{extattrs}{r7_site}{value}}). If they are the same, the site ID is stored to theL:site_id variable (${XC:COPY:{L:site_id}:{L:a_site{{id}}}}). If they are not the same, the execution is continued by the "check whether site list is empty" step.
Action Template: Get Site Configuration
...
{
"parse":
...
"XMLA",
...
"operation":
...
"POST",
...
"name":
...
"send
...
SiteConfigRequest",
...
"body_list":
...
[
...
"<?xml
...
version=\"1.0\"
...
encoding=\"UTF-8\"?>",
...
"<SiteConfigRequest
...
session-id=\"$
...
{S::SESSID
...
}\"
...
site-id=\"$
...
{L:A:site_id
...
}\"/>"
...
]
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"send
...
SiteConfigRequest
...
(error
...
check)",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{P:A:PARSE
...
[
...
[name
...
]
...
]
...
}",
...
"left":
...
"SiteConfigResponse"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"1",
...
"left":
...
"$
...
{P:A:PARSE
...
{
...
{success
...
}
...
}
...
}"
...
}
],
...
"condition_type":
...
"OR",
...
"else_eval":
...
"$
...
{XC:COPY:
...
{L:Site
...
}:
...
{P:PARSE
...
{SiteConfigResponse
...
}
...
}
...
}",
...
"error":
...
true
...
}
}
...
Note: Once site-id is known, steps "send SiteConfigRequest" and "send SiteConfigRequest (error check)" request and store the site configuration.
\\
\\
\\
...
Action Template: Distinguish Between INSERT and DELETE
...
{
"operation":
...
"CONDITION",
...
"name":
...
"check
...
operation
...
type
...
again",
...
"condition":
...
{
...
"statements":
...
[
...
{
...
"op":
...
"==",
...
"right":
...
"$
...
{E:A:operation_type
...
}",
...
"left":
...
"INSERT"
...
}
...
],
"condition_type": "AND",
...
"eval":
...
"$
...
{XC:COPY:
...
{L:network
...
}:
...
{E:values
...
{network
...
}
...
}
...
}$
...
{XC:NETWORKTORANGE:
...
{L:network
...
}:
...
{L:range
...
}
...
}",
...
"next":
...
"insert
...
network"
...
}
}
...
Note: The "check operation type again" step determines the operation type. If the operation is "INSERT", the network of the inserted fixed address is copied to the L:network variable ($\{XC:COPY:\{L:network\}:\{E:values\{network\}\}\}) and transformed to a Rapid7 range to the L:range variable ($\{XC:NETWORKTORANGE:\{L:network\}:\{L:range\}\}). After the range is stored, the template execution jumps to the "insert network" step.
\\
\\
\\
...
Action Template: Delete an IP Address
...
{
"operation":
...
"CONDITION",
...
"name":
...
"remove
...
ip",
...
"condition":
...
{
...
"statements":
...
[
...
{
...
"op":
...
"==",
...
"right":
...
"$
...
{E:A:event_type
...
}",
...
"left":
...
"FIXED_ADDRESS_IPV4"
...
}
...
],
...
"condition_type":
...
"AND",
...
"eval":
...
"$
...
{XC:COPY:
...
{L:ip
...
}:
...
{E:values
...
{ipv4addr
...
}
...
}
...
}$
...
{XC:REMOVEIP:
...
{L:ip
...
}:
...
{L:Site
...
{Hosts
...
}
...
}
...
}",
...
"else_eval":
...
"$
...
{XC:COPY:
...
{L:ip
...
}:
...
{E:values
...
{ipv6addr
...
}
...
}
...
}$
...
{XC:REMOVEIP:
...
{L:ip
...
}:
...
{L:Site
...
{Hosts
...
}
...
}
...
}"
...
}
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"jump
...
to
...
send",
...
"condition":
...
{
...
"statements":
...
[{
"op":
...
"==",
...
"right":
...
"",
...
"left":
...
""
...
}
...
],
...
"condition_type":
...
"AND",
...
"next":
...
"send
...
SiteSaveRequest"
...
}
}
NOTES:
- If the operation is not "
INSERT" (i.e. "DELETE"), the "remove ip" step is executed. The step determines the type of fixed address. The corresponding address ({E:values{ipv4addr}} or{E:values{ipv6addr}}) is copied to theL:ipvariable, and then theL:ipaddress is removed from the list of hosts in the site(${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}). - The step "
jump to send" skips the "inserting" step and jumps directly to the "send SiteSaveRequest" step.
Action Template: Add an IP Range
...
{
"operation":
...
"VARIABLEOP",
...
"name":
...
"insert
...
network",
...
"variable_ops": [{
"operation": "PUSH",
"type": "COMPOSITE",
"source": "L:range",
...
"destination":
...
"L:Site
...
{Site
...
}
...
{Hosts
...
}"
...
}
...
]
...
}
The step "insert
...
network"
...
pushes
...
the
...
L:range
...
to
...
the
...
list
...
of
...
site’s "Hosts".
...
Action
...
Template:
...
Saving
...
New
...
Configuration
...
{
...
"parse":
...
"XMLA",
...
"operation":
...
"POST",
...
"name":
...
"send
...
SiteSaveRequest",
...
"body_list":
...
[
...
"<?xml
...
version=\"1.0\"
...
encoding=\"UTF-8\"?>",
...
"<SiteSaveRequest
...
session-id=\"$
...
{S::SESSID
...
}\">",
...
"$
...
{L:x:Site
...
}",
...
"</SiteSaveRequest>"
...
]
},
...
{
"operation":
...
"CONDITION",
...
"name":
...
"send
...
SiteSaveRequest
...
(error
...
check)",
...
"condition":
...
{
...
"statements":
...
[
...
{
"op":
...
"!=",
...
"right":
...
"$
...
{P:A:PARSE
...
[
...
[name
...
]
...
]
...
}",
...
"left":
...
"SiteSaveResponse"
...
},
...
{
"op":
...
"!=",
...
"right":
...
"1",
...
"left":
...
"$
...
{P:A:PARSE
...
{
...
{success
...
}
...
}
...
}"
...
}
],
...
"condition_type":
...
"OR",
...
"error":
...
true
...
}
}
...
Note: The "send SiteSaveRequest" and "send SiteSaveRequest (error check)" steps save new site configuration to the Rapid7 server.
...
Action Template: Add Extensible Attributes Using WAPI
...
{
"operation":
...
"CONDITION",
...
"name":
...
"check
...
operation
...
type
...
once
...
more",
...
"condition":
...
{
...
"statements":
...
[{
"op":
...
"!=",
...
"right":
...
"$
...
{E:A:operation_type
...
}",
...
"left":
...
"INSERT"
...
}
...
],
...
"condition_type":
...
"AND",
...
"stop":
...
true
...
}
},
{
"operation": "PUT",
"name": "add an attribute with WAPI",
"transport": {"path":
...
"$
...
{E:A:values
...
{_ref
...
}
...
}"
...
},
...
"wapi":
...
"v2.6",
...
"body":
...
"
...
{\"extattrs+\":
...
{\"r7_added\":
...
{\"value\":
...
\"Added
...
to
...
the
...
Rapid7
...
$
...
{UT:A:TIME
...
}\"
...
}
...
}
...
}"
...
}
NOTES:
- The "
check operation type once more" step determines the operation type. If the operation is not "INSERT" (i.e. "DELETE"), the template execution stops. - For the "
INSERT" operation, the last step "add an attribute with WAPI" is executed. This step adds an extensible attribute "r7_added" to the fixed address through RESTful API. The value of the attribute has the current timestamp (${UT:A:TIME}).
Action Template: Add a Host Record
Wiki Markup
{
"version": "1.0",
"name": "Insert host record",
"comment": "Will automatically insert a host record for new network insertions, assumes the network has a 'Zone' extensible attribute, optionally a 'Hostname' extensible attribute as well",
"type": "REST_EVENT",
"event_type": [
"NETWORK_IPV4"
],
"action_type": "Insert a host record",
"vendor_identifier": "WAPI 2.3",
"transport": {
"content_type": "application/json",
},
"steps":
[
{
"name": "stop if it is not a network insert",
"operation": "CONDITION",
"condition": {
"condition_type": "AND",
"statements": [
{
"left": "${E:A:operation_type
...
}",
...
"op":
...
"!=",
...
"right":
...
"INSERT"
...
}
],
...
"stop":
...
true
...
}
},
{
"name":
...
"stop
...
if
...
we
...
don't
...
have
...
the
...
zone
...
EA
...
set,
...
else
...
save
...
it",
...
"operation":
...
"CONDITION",
...
"condition":
...
{
...
"condition_type":
...
"AND",
...
"statements":
...
[
{
"left": "${E:A:values{extattrs}{Zone}{value}}",
"op": "==",
...
"right":
...
""
...
}
],
...
"stop":
...
true,
...
"else_eval":
...
"$
...
{XC:COPY:
...
{L:ZONE
...
}:
...
{E:values
...
{extattrs
...
}
...
{Zone
...
}
...
{value
...
}
...
}
...
}"
...
}
},
...
{
"name":
...
"get
...
the
...
hostname
...
or
...
use
...
a
...
default
...
value",
...
"operation":
...
"CONDITION",
...
"condition":
...
{
...
"condition_type":
...
"AND",
...
"statements":
...
[
{
"left":
...
"$
...
{E:A:values
...
{extattrs
...
}
...
{Hostname
...
}
...
{value
...
}
...
}",
...
"op":
...
"!=",
...
"right":
...
""
...
}
],
...
"eval":
...
"$
...
{XC:COPY:
...
{L:HOSTNAME
...
}:
...
{E:values
...
{extattrs
...
}
...
{Hostname
...
}
...
{value
...
}
...
}
...
}",
...
"else_eval":
...
"$
...
{XC:ASSIGN:
...
{L:HOSTNAME
...
}:
...
{S:defaulthostname
...
}
...
}"
...
}
},
...
{
"name":
...
"insert
...
the
...
host
...
record
...
with
...
the
...
next
...
available
...
IP",
...
"operation":
...
"POST",
...
"transport":
...
{
...
"path":
...
"record:host"
...
},
...
"body_list":
...
[
...
"
...
{",
...
"\"name\":
...
\"$
...
{L:A:HOSTNAME
...
}.$
...
{L:A:ZONE
...
}\",",
...
"\"ipv4addrs\":
...
[
...
{\"ipv4addr\":
...
\"func:nextavailableip:$
...
{E:A:values
...
{network
...
}
...
}\"
...
}
...
],",
...
"\"comment\":
...
\"Inserted
...
via
...
outbound\"",
...
"
...
}"
...
]
}
]
}
| Anchor | ||||
|---|---|---|---|---|
|
Wiki Markup
Note that the execution of this sample template will cause a single *POST* request to be sent with the following body for an insertion of a *10.0.0.0/24* network with the Zone extensible attribute set to test.com and the Hostname extensible attribute set to * name:*
\
{"name":
...
"name.test.com","ipv4addrs":
...
[
...
{"ipv4addr":
...
"func:nextavailableip:10.0.0.0/24"
...
}
...
],"comment":
...
"Inserted
...
via
...
a
...
template"
...
}
...
Note: * The preamble of the template specifies the version, version, name and other relevant fields. \\ \\ \{
...
{ "version":
...
"1.0",
...
"name":
...
"Insert
...
host
...
record",
...
"comment":
...
"Will
...
automatically
...
insert
...
a
...
host
...
record
...
for
...
new
...
network
...
insertions,
...
assumes
...
the
...
network
...
has
...
a
...
'Zone'
...
extensible
...
attribute,
...
optionally
...
a
...
'Hostname'
...
extensible
...
attribute
...
as
...
well",
...
"type":
...
"REST_EVENT",
...
...
Note: * The event_type field specifies that this template is used for IPv4 network events only.
\\
\\
...
"event_type":
...
[
...
"NETWORK_IPV4"
...
],
...
...
Note: * The action_type and vendor_identifier fields describe the template type and the vendor type.
\\
\\
...
"action_type":
...
"Insert
...
a
...
host
...
record",
...
"vendor_identifier":
...
"WAPI
...
2.3",
...
...
Note: * The following specifies that the template is going to send JSON to the server. \\ \\
...
"transport":
...
{
"content_type":
...
"application/json",
...
},
...
...
Note: * The following are steps that will be executed sequentially. \\ \\
...
"steps":
...
[
...
Note: The first step will stop the execution, without an error, if the network event received is not an insertion – it could be a modify, for example.
...
{
"name": "stop if it is not a network insert",
"operation": "CONDITION",
"condition": {
...
Note: You can only one statement: either AND or OR would work.
...
"condition_type":
...
"AND",
...
"statements":
...
[
...
Note: * The match is to check if operation_type in the event is different from INSERT. It is a good practice to put the event variable on the left side so if it is not present in the event, the template would not fail.
\\
\\
\{
...
{
"left":
...
"$
...
{E:A:operation_type
...
}",
...
"op":
...
"!=",
...
"right":
...
"INSERT"
...
}
...
],
...
...
Note: * The directive that stops the execution if the condition matches. \\ \\
...
"stop":
...
true
...
}
...
},
...
...
Note: * The second step will stop the execution if the inserted network does not have the Zone extensible attribute configured. If it has the extensible attribute, it will be put in a temporary local variable for easier access later on. \\ \\ \\ \\ !worddav82aac1426f41e4bf41b080762501fdd1.png|height=20,width=11! 1834NIOS Administrator Guide (Rev. A)NIOS 8.1 Sample Templates \\ \\ \{ on.
...
{
"name":
...
"stop
...
if
...
we
...
don't
...
have
...
the
...
zone
...
EA
...
set,
...
else
...
save
...
it",
...
"operation":
...
"CONDITION",
...
"condition":
...
{
...
Note: * Similar to the previous section, we have only one statement, so either AND or OR would work. The condition ensures that the Zone extensible attribute is set to a value. \\ \\
...
"condition_type":
...
"AND",
...
"statements":
...
[
...
{
...
Note: As previously mentioned, non-existent variable access in the left side of a condition will not cause an error, but instead return an empty value. \\ \\
...
"left":
...
"$
...
{E:A:values
...
{extattrs
...
}
...
{Zone
...
}
...
{value
...
}
...
}",
...
"op":
...
"==",
...
"right":
...
""
...
}
...
],
...
...
Note: * If the extensible attribute is empty or nonexistent, the operation should stop here. \\ \\
...
"stop":
...
true,
...
...
Note: * Otherwise, it will copy the zone value to the local ZONE variable. \\ \\
...
"else_eval":
...
"$
...
{XC:COPY:
...
{L:ZONE
...
}:
...
{E:values
...
{extattrs
...
}
...
{Zone
...
}
...
{value
...
}
...
}
...
}"
...
}
...
},
...
...
Note: This step is similar to the zone step above. However, if the host name is not set, it will put a default host name in a local variable to provide the default.
...
{
"name": "get the hostname or use a default value",
"operation": "CONDITION",
"condition": {
"condition_type":
...
"AND",
...
"statements":
...
[
...
{
...
"left":
...
"$
...
{E:A:values
...
{extattrs
...
}
...
{Hostname
...
}
...
{value
...
}
...
}",
...
"op":
...
"!=",
...
"right":
...
""
...
}
...
],
...
...
Note: This is executed if the extensible attribute is present, by copying its value to HOSTNAME.
...
"eval":
...
"$
...
{XC:COPY:
...
{L:HOSTNAME
...
}:
...
{E:values
...
{extattrs
...
}
...
{Hostname
...
}
...
{value
...
}
...
}
...
}",
...
...
Note: * Otherwise, the following is executed if the extensible attribute is empty or not present, by assigning the *defaulthostname* string instead.
\\
\\
...
"else_eval":
...
"$
...
{XC:ASSIGN:
...
{L:HOSTNAME
...
}:
...
{S:defaulthostname
...
}
...
}"
...
}
...
},
...
Note: This step will finally contact the endpoint and in this case insert the host.
...
{"name": "insert the host record with the next available IP",
...
Note: This defines the HTTP operation to use.
...
"operation": "POST",
...
Note: The endpoint is configured starting with https://master_ip/...{_}. The endpoint template overrides the path with _/wapi/v2.3/_ so by default all template requests would go to _https://master_ip/wapi/v2.3/{_}. In this step, we want to insert a host, so record:host is appended to the URI above (no override is set here) to arrive to the valid RESTful URI _https://master_ip/wapi/v2.3/record:host{_}.
\\
\\
.
...
"transport":
...
{
...
"path":
...
"record:host"
...
},
...
...
Note: * This is the text that will be sent to the server in the POST's POST’s BODY. \\ \\
...
"body_list":
...
[
...
"
...
{",
...
...
Note: * This references the local variables that were previously assigned. \\ \\
...
"\"name\":
...
\"$
...
{L:A:HOSTNAME
...
}.$
...
{L:A:ZONE
...
}\",",
...
...
Note: * This option signifies that the RESTful API will use the next available IP in the network as the address for this host. \\ \\ "\"ipv4addrs\": \[\{\"ipv4addr\": \"func:nextavailableip:$\{E:A:values\{network\}\}\"\}\],", \\ \\ *Note:* This is the comment stating that the action is done through the RESTful API template. \\ \\ "\"comment\": \"Inserted via outbound\"", "\}" \] \} \] \} \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ !worddav82aac1426f41e4bf41b080762501fdd1.png|height=20,width=11! 1836NIOS Administrator Guide (Rev. A)NIOS 8.1 \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\the network as the address for this host.
...
"\"ipv4addrs\": [{\"ipv4addr\":
\"func:nextavailableip:${E:A:values{network}}\"}],",
...
Note: This is the comment stating that the action is done through the RESTful API template.
...
"\"comment\": \"Inserted via outbound\"","}"
]
}
]
}