TCL script "exec" command usage and parameters

[Katoomba]

In TCL scripts, the "exec" command is used to send text strings to the Fortigates and Fortigate output is then returned to the TCL script which can then be processed by TCL.

A typical example would look like:

exec "get system status\n" "# " 10

The first parameter is the text to be sent to the Fortigate with \n being the new line character used to terminate the command.

The second parameter (in the above case, "# ") is the string that the Fortigate should return to exec which exec should wait for before moving on.

The third parameter (in the above case, 10) is (perhaps suspected to be) the timeout value which tells exec to wait up to 10 seconds for the "# " string to be returned by the Fortigate before exec will give up waiting and move on.

However, I have searched for details on the second and third parameters and have not been able to confirm the precise usage requirements for either parameters.

In the case of the second parameter - the matching string. Is the string a regex or just a simple text string?

For example, is the following a valid exec command? Note the second parameter. Since it is a regex, it should match on both # and on $. If the string is not a regex, can it be a comma delimited string to match on different strings. Or is the value restricted to just one string?

exec "$cmd\n" " (#|\$) " 10

In the case of the third parameter - the suspected timeout. What is the valid range of values? For example, are the following exec commands valid? Note the third parameter. They are set to 5 and 20 (seconds) .

exec "$cmd\n" " (#|\$) " 5
exec "$cmd\n" " (#|\$|>) " 20

Are there any other values that are valid for the second and third parameters?

Do you have any other details of correct operation and use of the exec command?

[dingjerry_FTNT]

Hi @Katoomba ,

In this doc, there is an example for the TCL script:

https://docs.fortinet.com/document/fortimanager/7.6.1/administration-guide/914165/tcl-scripts

I hope it will help you.

[Katoomba]

That document does not help with any of my questions. Upon reviewing the document in detail, it brings up some more questions about the exec function.

One of the examples shows that the third parameter (the timeout?) is not used at all. So it seems that the third parameter is optional. In which case, when it is omitted, what is the default value?

And, the examples show different values (15 and 30) for the third parameter.

Also, a procedure for a simplified way to execute commands is given.

proc do_cmd {cmd} {
  puts [exec "$cmd\n" "# " 15]
}

However, no explanation is given for why the exec command should be encapsulated within the "puts". And, there is an unwanted side effect of placing the command within the puts in that the command output is always displayed in the TCL script results. The following procedure works just as well but doesn't clutter up the script results screen.

proc do_cmd {cmd} {
  return exec "$cmd\n" "# " 15
}

So why put the "exec" within the "puts"?

Details like this really should be in the documentation already. It's 2024 and the TCL script feature has been supported in FMG since version 5.

[Katoomba]

I also discovered an interesting behavior of TCL script execution history output. Sometimes, the execution history will be displayed in red text even though no error has occurred. The script executes perfectly, does everything it should, but the execution history is displayed as all red text.

What I discovered is that if ANY of the text found in the execution history contains the output "fail" or "error" (case insensitive), then the entire execution results text will be shown in red.

Are there any other behaviors that we humble users might want to know about? Don't get me wrong. I am not trying to be rude. But TCL scripts have been a feature in Fortimanager for many, many years and some of these "features" ought to be documented.

The following TCL script executes perfectly. But it always displays execution history in red text because the red is triggered by "fail" in the command "edit failover".

#!/usr/bin/tclsh
#########################################################################################
# defined procedures section
#########################################################################################
# execute commands
proc do_cmd {cmd} {
  puts [exec "$cmd\n" " # " 10]
}
#########################################################################################
# 'main' section
#########################################################################################
do_cmd "config global"
do_cmd "config system alias"
do_cmd "edit \"failover\""
do_cmd "set command \"diag system ha reset-uptime\n\""
do_cmd "next"
do_cmd "end"
#########################################################################################

The following script displays the execution history in normal black on white.

#!/usr/bin/tclsh
#########################################################################################
# defined procedures section
#########################################################################################
# execute commands
proc do_cmd {cmd} {
  puts [exec "$cmd\n" " # " 10]
}
#########################################################################################
# 'main' section
#########################################################################################
do_cmd "config global"
do_cmd "config system alias"
exec "edit \"failover\"\n" " # " 10
exec "set command \"diag system ha reset-uptime\n\"\n" " # " 10
do_cmd "next"
do_cmd "end"
#########################################################################################

Note that I twice used the exec command to apply the "edit failover" and to set the command (because the word failover appears in the return prompt too) which resulted in there being no output returned to TCL that contained text "fail". Thus, the execution history shows up black text on white.

Which returns me to one of my earlier questions. Why use "puts" in the do_cmd procedure? Because removing the "puts" stops the output from being sent to the execution history which in turn stops the triggering of red text.