[Draft] Config Push - new modifiers and actions in 2.4

[Tomas]

Hi everyone,

For 2.4, we are planning to rework how behavior modifiers work in Mass Config Push. This relates to the current way modifiers work, and improves upon the current syntax. We are also introducing a new concept of "actions", which will replace how control sequences are sent currently.

We would love your feedback on the changes. Here is our current plan:

All available macros:

Code: Select all

$() - modifiers and actions
${} - variables

Modifiers and actions:
Modifiers: Modifiers are two-word macros and must always be at the end of a line. Multiple consecutive modifiers are allowed. A single modifier can only be declared once.

Code: Select all

Allowed modifiers:
wait-echo, wait-reply, enter, fail-on-error

example: $(enter yes)

valid usage: show version$(enter no)
invalid usage: show $(wait-reply no) version

Actions: Actions are two-word macros and can be placed at any position in a line.

Code: Select all

Allowed actions:
delay, send

example: $(delay 100), $(send 0x01)

Built-in constants:
Constants are single-word macros and can be placed at any position in a line. Only available pre-defined constants can be used. Constants are device's properties, hence a relevant constant will always contain the requested data for each device.

Code: Select all

Available constants:
address, description, vendor, type, model, zone-name, zone-description, zone-id

User variables:
Variables are single-word macros and can be placed at any position in a line. Any variable name (single-word, without space) can be used, and you defines these in GUI (Devices > Variables).

Code: Select all

example: ${foo}, ${bar}

usage example:
interface vlan ${vlan-id}
set description ${vlan-description}

How variable values are resolved:
If a variable is declared in Push commands, it's value can come from a built-in constant, or a user-defined variable. User-defined variables always have MORE priority during variable substitution than built-in constants. For example, if you define a user variable "${address}", when you use "${address}" in a preset, on devices which have this user-variable defined, it will be used instead of a constant.

Constant overriding:
As described above, built-in constants can be overridden by the user (you) just by defining a user-defined variable of the same name on the device. In short, when evaluating variables, Unimus will try to use user-defined variables, and if that fails, try to use built-in constants. If the declared variable name is not available in either, the Push will fail.

[Tomas]

The point of these changes is to introduce consistent handling of behavior modifiers, constants and variables in Config Push, and to introduce new things (like the new action concept, and constants as a whole). All modifiers now for example have a default value of "yes", so understanding how they behave should be much easier for new users. As an example,

Code: Select all

show version

is equivalent to

Code: Select all

show version$(wait-echo yes)$(wait-reply yes)$(enter yes)$(fail-on-error yes)

Before 2.4 (in current stable releases), this is a bit more messy, as you have "$[enter]" and "$[no-enter]" as separate macros, and you could for example declare both on a single line, which gets messy fast.

Full documentation for the new macros will be available on the Wiki closer to the 2.4 release. For now, here is an (on purpose complex) example of a combination of all of these concepts in a Config Push preset:

Code: Select all

show firmware
firmware apply os-${vendor}-${type}-${os-version}.img$(wait-reply no)
$(delay 1000)y$(delay 1000)y$(enter no)$(wait-echo no)
boot set os-${vendor}-${type}-${os-version}.img$(fail-on-error no)
show firmware
reboot now
y$(delay 250)$(enter no)$(wait-echo no)$(wait-reply no)

[Tomas]

UPDATE:

In a previous draft, we proposed the macro syntax to look like this:

Code: Select all

$() - modifiers and actions
$[] - built-in constants
${} - user variables

There was a distinction between device constants, and user-defined variables. Due to your feedback, how this is declared in Push commands and how this is handled is being changed. There are only 2 macro declaration formats now:

Code: Select all

$() - modifiers and actions
${} - variables

Built-in device constants are defined the same way as variables now - this helps fight the "which brackets should I use" syndrome, and allows us to do a cool new thing - variable priority and overriding.

How this will work is that you can use the "${address}" variable on a device, and if it's not a user-defined variable, the built-in constant will be used. In short, when evaluating variables, Unimus will try to use user-defined variables, and if that fails, try to use built-in constants. If the declared variable name is not available in either, the Push will fail.

All above posts were adjusted to reflect this change.