1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
# RouterOS items
Manages RouterOS configuration through the API (port 8728). You can address every configuration exposed by the API by
constructing the item name and attributes accordingly. If you haven't already, familiarize yourself with the CLI over
SSH first. Use it as a reference when composing items in your bundles. <strong>Don't forget to set the <code>os</code>
attribute of your node to <code>routeros</code> and also set the <code>username</code> and <code>password</code>
attributes.</strong>
routeros = {
"/ip/dns": {
"servers": "8.8.8.8",
},
"/interface/vlan?name=vlan6": {
"vlan-id": "6",
"interface": "bridge",
"needs": {
"routeros:/interface/bridge?name=bridge",
},
},
"/interface/vlan?name=vlan7": {
"delete": True,
},
"/interface/vlan": {
"purge": {
"id-by": "name",
},
},
"/interface/bridge?name=bridge": {},
"/interface/bridge/port?interface=ether8": {
"bridge": "bridge",
"needs": {
"routeros:/interface/bridge?name=bridge",
},
},
"/interface/bridge/port": {
"purge": {
"id-by": "interface",
},
},
"/interface/bridge/vlan?vlan-ids=6": {
"bridge": "bridge",
"needs": {
"routeros:/interface/bridge?name=bridge",
},
"tagged": {
"ether10",
"ether11",
"ether12",
},
"untagged": {
"ether13",
"ether14",
"ether15",
},
},
"/interface/bridge/vlan": {
"purge": {
"id-by": "vlan-ids",
"keep": {
"dynamic": True,
},
},
},
"/interface/bonding?name=LAG1": {
"mode": "802.3ad",
"slaves": ["ether2", "ether3"],
"transmit-hash-policy": "layer-3-and-4",
},
"/interface/bonding": {
"purge": {
"id-by": "name",
},
},
"/system/logging?action=remote&topics=critical": {},
}
Note that when configuring an item from a list of things, item names have two parts, separated by a `?` character. The
first part determines which kind of item is addressed, the second part is a simple `key=value` query that MUST return
exactly one entry. If a list has no single "primary key" (such as `/system/logging`), use `&` to add more conditions.
For lists of things, the purge option can be used to instruct BundleWrap to remove items it doesn't know about (see the
Purging section).
For example `/interface/vlan` addresses all VLAN interfaces (a list of things) and can be configured to purge unmanaged
VLANs, whereas `/interface/vlan?name=vlan7` configures a specific VLAN.
# Purging
For any lists of things (VLAN interfaces, bonds) the purge option can be enabled:
```
"/interface/vlan?name=vlan6": {
"vlan-id": "6",
"interface": "bridge",
"needs": {
"routeros:/interface/bridge?name=bridge",
},
},
"/interface/vlan": {
"purge": {
"id-by": "name",
},
},
```
The `id-by` option tells BundleWrap to identify configured items by the specified key. In the above example, BundleWrap
searches for all items with item ids starting wih `/interface/vlan` that contain a `name` key. It
finds `/interface/vlan?name=vlan6` and assumes that only one VLAN should be configured and it should have a `name`
of `vlan6`. It will then delete any VLANs on the node not matching this selection.
For different items, different selection keys are useful. For example for bridge ports, the `interface` key is often
used:
```
"/interface/bridge/port?interface=ether8": {
"bridge": "bridge",
"needs": {
"routeros:/interface/bridge?name=bridge",
},
},
"/interface/bridge/port": {
"purge": {
"id-by": "interface",
},
},
```
Again, the managed items under the `/interface/bridge/port` path are identified by the `interface` key and this key is
also used to select items to be purged.
For some types of items, not all subitems can be deleted. For example `/interface/bridge/vlan` will also list dynamic
VLANs which are not configured and can thus not be removed. They automatically appear/disappear with the bridge ports
using them.
In these cases, additional attributes can be specified in the `keep` option. Any item on the node that has any
attribute matching the `keep` filter will also be retained and not purged.
```
"/interface/bridge/vlan": {
"purge": {
"id-by": "vlan-ids",
"keep": {
"dynamic": True,
},
},
},
```
# Attribute reference
See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
<hr>
<strong>BundleWrap will accept any attributes for these items and pass them through to the RouterOS API.</strong> All
attribute values can be passed as strings. If given as integers or booleans, BundleWrap will convert them to strings for
you. If given a set, list, or tuple of strings, BundleWrap will join those strings with commas.
Since `comment` is an internal attribute for BundleWrap, use `_comment` to apply the `comment` attribute on a RouterOS
item.
<hr>
## delete
When set to `True`, this item will be removed from the system. When using `delete`, no other attributes are allowed.
|
