Fortinet black logo

CLI Reference

Tips

Tips

Basic features and characteristics of the CLI environment provide support and ease of use for many CLI tasks.

Help

To display brief help during command entry, press the question mark (?) key.

  • Press the question mark (?) key at the command prompt to display a list of the commands available and a description of each command.
  • Type a word or part of a word, then press the question mark (?) key to display a list of valid word completions or subsequent words, and to display a description of each.

Shortcuts and key commands

Keys Action

?

List valid word completions or subsequent words.

If multiple words could complete your entry, display all possible completions with helpful descriptions of each.

Tab

Complete the word with the next available match.

Press the Tab key multiple times to cycle through available matches.

Up arrow, or Ctrl + P

Recall the previous command.

Command memory is limited to the current session.

Down arrow, or Ctrl + N

Recall the next command.

Left or Right arrow

Move the cursor left or right within the command line.

Ctrl + A

Move the cursor to the beginning of the command line.

Ctrl + E

Move the cursor to the end of the command line.

Ctrl + B

Move the cursor backwards one word.

Ctrl + F

Move the cursor forwards one word.

Ctrl + D

Delete the current character.

Ctrl + C

Abort current interactive commands, such as when entering multiple lines.

If you are not currently within an interactive command such as config or edit, this closes the CLI connection.

\ then Enter

Continue typing a command on the next line for a multiline command.

For each line that you want to continue, terminate it with a backslash ( \ ). To complete the command line, terminate it by pressing the spacebar and then the Enter key, without an immediately preceding backslash.

Command abbreviation

You can abbreviate words in the command line to their smallest number of non-ambiguous characters.

For example, the command get system status could be abbreviated to g sy stat.

Adding and removing options from lists

When adding options to a list, such as a user group, using the set command will remove the previous configuration. For example, if you wish to add user D to a user group that already contains members A, B, and C, the command would need to be set member A B C D. If only set member D was used, then all former members would be removed from the group.

However, there are additional commands which can be used instead of set for changing options in a list.

Additional commands for lists

append

Add an option to an existing list.

For example, append member would add user D to a user group while all previous group members are retained

select

Clear all options except for those specified.

For example, if a group contains members A, B, C, and D and you remove all users except for B, use the command select member B.

unselect

Remove an option from an existing list.

For example, unselect member A would remove member A from a group will all previous group members are retained.

Environment variables

The CLI supports the following environment variables. Variable names are case-sensitive.

Environment variables

$USERFROM

The management access type (ssh, telnet, jsconsole for the CLI Console widget in the GUI, and so on) and the IP address of the administrator that configured the item.

$USERNAME

The account name of the administrator that configured the item.

$SerialNum

The serial number of the FortiGate unit.

For example, the FortiGate unit’s host name can be set to its serial number:

config system global

set hostname $SerialNum

end

Special characters

The following special characters, also known as reserved characters, are not permitted in most CLI fields: <, >, (, ), #, ', and ". You may be able to enter special characters as part of a string’s value by using a special command, enclosing it in quotes, or preceding it with an escape sequence — in this case, a backslash ( \ ) character.

In other cases, different keystrokes are required to input a special character. If you need to enter ? as part of config, you first need to input CTRL-V. If you enter ? without first using CTRL-V, the question mark has a different meaning in the CLI; it will show available command options in that section.

For example, if you enter ? without CTRL-V:

edit "*.xe

token line: Unmatched double quote.

If you enter ? with CTRL-V:

edit "*.xe?"

new entry '*.xe?' added

Entering special characters
Character Keys

?

Ctrl + V then ?

Tab

Ctrl + V then Tab

Space

(to be interpreted as part of a string value, not to end the string)

Enclose the string in quotation marks: "Security Administrator”.

Enclose the string in single quotes: 'Security Administrator'.

Precede the space with a backslash: Security\ Administrator.

'

(to be interpreted as part of a string value, not to end the string)

\'

"

(to be interpreted as part of a string value, not to end the string)

\"

\

\\

Using grep to filter get and show command output

In many cases, the get and show (and diagnose) commands may produce a large amount of output. If you are looking for specific information in a large get or show command output, you can use the grep command to filter the output to only display what you are looking for. The grep command is based on the standard UNIX grep, used for searching text output based on regular expressions.

Use the following command to display the MAC address of the FortiGate unit internal interface:

get hardware nic internal | grep Current_HWaddr

Current_HWaddr 00:09:0f:cb:c2:75

Use the following command to display all TCP sessions in the session list and include the session list line number in the output:

get system session list | grep -n tcp

Use the following command to display all lines in HTTP replacement message commands that contain URL (upper or lower case):

show system replacemsg http | grep -i url

There are three additional options that can be applied to grep:

-A <num> After

-B <num> Before

-C <num> Context

The option -f is also available to support contextual output, in order to show the complete configuration. The following example shows the difference in output when -f option is used versus when it is not.

Using -f:

show | grep -f ldap-group1

config user group

edit "ldap-group1"

set member "pc40-LDAP"

next

end

config firewall policy

edit 2

set srcintf "port31"

set dstintf "port32"

set srcaddr "all"

set action accept

set identity-based enable

set nat enable

config identity-based-policy

edit 1

set schedule "always"

set groups "ldap-group1"

set dstaddr "all"

set service "ALL"

next

end

next

end

Without using -f:

show | grep ldap-group1

edit "ldap-group1"

set groups "ldap-group1"

Language support and regular expressions

Characters such as ñ, é, symbols, and ideographs are sometimes acceptable input. Support varies by the nature of the item being configured. CLI commands, objects, field names, and options must use their exact ASCII characters, but some items with arbitrary names or values may be input using your language of choice. To use other languages in those cases, you must use the correct encoding.

Input is stored using Unicode UTF-8 encoding but is not normalized from other encodings into UTF-8 before it is stored. If your input method encodes some characters differently than in UTF-8, your configured items may not display or operate as expected.

Regular expressions are especially impacted. Matching uses the UTF‑8 character values. If you enter a regular expression using another encoding, or if an HTTP client sends a request in an encoding other than UTF‑8, matches may not be what you expect.

For example, with Shift-JIS, backslashes ( \ ) could be inadvertently interpreted as the symbol for the Japanese yen ( ¥ ) and vice versa. A regular expression intended to match HTTP requests containing money values with a yen symbol therefore may not work it if the symbol is entered using the wrong encoding.

For best results, you should:

  • use UTF-8 encoding, or
  • use only the characters whose numerically encoded values are the same in UTF‑8, such as the US-ASCII characters that are also encoded using the same values in ISO 8859-1, Windows code page 1252, Shift-JIS and other encodings, or
  • for regular expressions that must match HTTP requests, use the same encoding as your HTTP clients.

note icon

HTTP clients may send requests in encodings other than UTF-8. Encodings usually vary by the client’s operating system or input language. If you cannot predict the client’s encoding, you may only be able to match any parts of the request that are in English, because regardless of the encoding, the values for English characters tend to be encoded identically. For example, English words may be legible regardless of interpreting a web page as either ISO 8859-1 or as GB2312, whereas simplified Chinese characters might only be legible if the page is interpreted as GB2312.

If you configure your FortiGate unit using other encodings, you may need to switch language settings on your management computer, including for your web browser or Telnet/SSH client. For instructions on how to configure your management computer’s operating system language, locale, or input method, see its documentation.

If you choose to configure parts of the FortiGate unit using non-ASCII characters, verify that all systems interacting with the FortiGate unit also support the same encodings. You should also use the same encoding throughout the configuration if possible in order to avoid needing to switch the language settings of the GUI and your web browser or Telnet/SSH client while you work.

Similarly to input, your web browser or CLI client should normally interpret display output as encoded using UTF-8. If it does not, your configured items may not display correctly in the GUI or CLI. Exceptions include items such as regular expressions that you may have configured using other encodings in order to match the encoding of HTTP requests that the FortiGate unit receives.

To enter non-ASCII characters in the CLI console:
  1. On your management computer, start your web browser and go to the URL for the FortiGate unit’s GUI.
  2. Configure your web browser to interpret the page as UTF-8 encoded.
  3. Log in to the FortiGate unit.
  4. Open the CLI Console from the upper right-hand corner.
  5. In the title bar of the CLI Console widget, click Edit (the pencil icon).
  6. Enable Use external command input box and select OK.
  7. The Command field appears below the usual input and display area of the CLI Console .
  8. Type a command in this field and press Enter.

In the display area, the CLI Console widget displays your previous command interpreted into its character code equivalent, such as:

edit \743\601\613\743\601\652

and the command’s output.

To enter non-ASCII characters in a Telnet/SSH client
  1. On your management computer, start your Telnet or SSH client.
  2. Configure your Telnet or SSH client to send and receive characters using UTF-8 encoding.

    Support for sending and receiving international characters varies by each Telnet/SSH client. Consult the documentation for your Telnet/SSH client.

  3. Log in to the FortiGate unit.
  4. At the command prompt, type your command and press Enter.

    You may need to surround words that use encoded characters with single quotes ( ' ).

    Depending on your Telnet/SSH client’s support for your language’s input methods and for sending international characters, you may need to interpret them into character codes before pressing Enter.

    For example, you might need to enter:

    edit '\743\601\613\743\601\652'

  5. The CLI displays your previous command and its output.

Screen paging

You can configure the CLI to pause after displaying each page’s worth of text when displaying multiple pages of output. When the display pauses, the last line displays ‑‑More‑‑. You can then either:

  • press the spacebar to display the next page.
  • type Q to truncate the output and return to the command prompt.

This may be useful when displaying lengthy output, such as the list of possible matching commands for command completion, or a long list of settings. Rather than scrolling through or possibly exceeding the buffer of your terminal emulator, you can simply display one page at a time.

To configure the CLI Console to pause display when the screen is full:

config system console

set output more

end

Baud rate

You can change the default baud rate of the local console connection.

To change the baud rate enter the following commands:

config system console

set baudrate {9600 | 19200 | 38400 | 57600 | 115200}

end

Editing the configuration file on an external host

You can edit the FortiGate configuration on an external host by first backing up the configuration file to a TFTP server. Then edit the configuration file and restore it to the FortiGate unit.

Editing the configuration on an external host can be timesaving if you have many changes to make, especially if your plain text editor provides advanced features such as batch changes.

To edit the configuration on your computer:
  1. Use execute backup to download the configuration file to a TFTP server, such as your management computer.
  2. Edit the configuration file using a plain text editor that supports Unix-style line endings.

    caution icon

    Do not edit the first line. The first line(s) of the configuration file (preceded by a # character) contains information about the firmware version and FortiGate model. If you change the model number, the FortiGate unit will reject the configuration file when you attempt to restore it.

  3. Use execute restore to upload the modified configuration file back to your FortiGate.

    The FortiGate downloads the configuration file and checks that the model information is correct. If it is correct, the FortiGate unit loads the configuration file and checks each command for errors. If a command is invalid, the FortiGate unit ignores the command. If the configuration file is valid, the FortiGate unit restarts and loads the new configuration.

Tips

Basic features and characteristics of the CLI environment provide support and ease of use for many CLI tasks.

Help

To display brief help during command entry, press the question mark (?) key.

  • Press the question mark (?) key at the command prompt to display a list of the commands available and a description of each command.
  • Type a word or part of a word, then press the question mark (?) key to display a list of valid word completions or subsequent words, and to display a description of each.

Shortcuts and key commands

Keys Action

?

List valid word completions or subsequent words.

If multiple words could complete your entry, display all possible completions with helpful descriptions of each.

Tab

Complete the word with the next available match.

Press the Tab key multiple times to cycle through available matches.

Up arrow, or Ctrl + P

Recall the previous command.

Command memory is limited to the current session.

Down arrow, or Ctrl + N

Recall the next command.

Left or Right arrow

Move the cursor left or right within the command line.

Ctrl + A

Move the cursor to the beginning of the command line.

Ctrl + E

Move the cursor to the end of the command line.

Ctrl + B

Move the cursor backwards one word.

Ctrl + F

Move the cursor forwards one word.

Ctrl + D

Delete the current character.

Ctrl + C

Abort current interactive commands, such as when entering multiple lines.

If you are not currently within an interactive command such as config or edit, this closes the CLI connection.

\ then Enter

Continue typing a command on the next line for a multiline command.

For each line that you want to continue, terminate it with a backslash ( \ ). To complete the command line, terminate it by pressing the spacebar and then the Enter key, without an immediately preceding backslash.

Command abbreviation

You can abbreviate words in the command line to their smallest number of non-ambiguous characters.

For example, the command get system status could be abbreviated to g sy stat.

Adding and removing options from lists

When adding options to a list, such as a user group, using the set command will remove the previous configuration. For example, if you wish to add user D to a user group that already contains members A, B, and C, the command would need to be set member A B C D. If only set member D was used, then all former members would be removed from the group.

However, there are additional commands which can be used instead of set for changing options in a list.

Additional commands for lists

append

Add an option to an existing list.

For example, append member would add user D to a user group while all previous group members are retained

select

Clear all options except for those specified.

For example, if a group contains members A, B, C, and D and you remove all users except for B, use the command select member B.

unselect

Remove an option from an existing list.

For example, unselect member A would remove member A from a group will all previous group members are retained.

Environment variables

The CLI supports the following environment variables. Variable names are case-sensitive.

Environment variables

$USERFROM

The management access type (ssh, telnet, jsconsole for the CLI Console widget in the GUI, and so on) and the IP address of the administrator that configured the item.

$USERNAME

The account name of the administrator that configured the item.

$SerialNum

The serial number of the FortiGate unit.

For example, the FortiGate unit’s host name can be set to its serial number:

config system global

set hostname $SerialNum

end

Special characters

The following special characters, also known as reserved characters, are not permitted in most CLI fields: <, >, (, ), #, ', and ". You may be able to enter special characters as part of a string’s value by using a special command, enclosing it in quotes, or preceding it with an escape sequence — in this case, a backslash ( \ ) character.

In other cases, different keystrokes are required to input a special character. If you need to enter ? as part of config, you first need to input CTRL-V. If you enter ? without first using CTRL-V, the question mark has a different meaning in the CLI; it will show available command options in that section.

For example, if you enter ? without CTRL-V:

edit "*.xe

token line: Unmatched double quote.

If you enter ? with CTRL-V:

edit "*.xe?"

new entry '*.xe?' added

Entering special characters
Character Keys

?

Ctrl + V then ?

Tab

Ctrl + V then Tab

Space

(to be interpreted as part of a string value, not to end the string)

Enclose the string in quotation marks: "Security Administrator”.

Enclose the string in single quotes: 'Security Administrator'.

Precede the space with a backslash: Security\ Administrator.

'

(to be interpreted as part of a string value, not to end the string)

\'

"

(to be interpreted as part of a string value, not to end the string)

\"

\

\\

Using grep to filter get and show command output

In many cases, the get and show (and diagnose) commands may produce a large amount of output. If you are looking for specific information in a large get or show command output, you can use the grep command to filter the output to only display what you are looking for. The grep command is based on the standard UNIX grep, used for searching text output based on regular expressions.

Use the following command to display the MAC address of the FortiGate unit internal interface:

get hardware nic internal | grep Current_HWaddr

Current_HWaddr 00:09:0f:cb:c2:75

Use the following command to display all TCP sessions in the session list and include the session list line number in the output:

get system session list | grep -n tcp

Use the following command to display all lines in HTTP replacement message commands that contain URL (upper or lower case):

show system replacemsg http | grep -i url

There are three additional options that can be applied to grep:

-A <num> After

-B <num> Before

-C <num> Context

The option -f is also available to support contextual output, in order to show the complete configuration. The following example shows the difference in output when -f option is used versus when it is not.

Using -f:

show | grep -f ldap-group1

config user group

edit "ldap-group1"

set member "pc40-LDAP"

next

end

config firewall policy

edit 2

set srcintf "port31"

set dstintf "port32"

set srcaddr "all"

set action accept

set identity-based enable

set nat enable

config identity-based-policy

edit 1

set schedule "always"

set groups "ldap-group1"

set dstaddr "all"

set service "ALL"

next

end

next

end

Without using -f:

show | grep ldap-group1

edit "ldap-group1"

set groups "ldap-group1"

Language support and regular expressions

Characters such as ñ, é, symbols, and ideographs are sometimes acceptable input. Support varies by the nature of the item being configured. CLI commands, objects, field names, and options must use their exact ASCII characters, but some items with arbitrary names or values may be input using your language of choice. To use other languages in those cases, you must use the correct encoding.

Input is stored using Unicode UTF-8 encoding but is not normalized from other encodings into UTF-8 before it is stored. If your input method encodes some characters differently than in UTF-8, your configured items may not display or operate as expected.

Regular expressions are especially impacted. Matching uses the UTF‑8 character values. If you enter a regular expression using another encoding, or if an HTTP client sends a request in an encoding other than UTF‑8, matches may not be what you expect.

For example, with Shift-JIS, backslashes ( \ ) could be inadvertently interpreted as the symbol for the Japanese yen ( ¥ ) and vice versa. A regular expression intended to match HTTP requests containing money values with a yen symbol therefore may not work it if the symbol is entered using the wrong encoding.

For best results, you should:

  • use UTF-8 encoding, or
  • use only the characters whose numerically encoded values are the same in UTF‑8, such as the US-ASCII characters that are also encoded using the same values in ISO 8859-1, Windows code page 1252, Shift-JIS and other encodings, or
  • for regular expressions that must match HTTP requests, use the same encoding as your HTTP clients.

note icon

HTTP clients may send requests in encodings other than UTF-8. Encodings usually vary by the client’s operating system or input language. If you cannot predict the client’s encoding, you may only be able to match any parts of the request that are in English, because regardless of the encoding, the values for English characters tend to be encoded identically. For example, English words may be legible regardless of interpreting a web page as either ISO 8859-1 or as GB2312, whereas simplified Chinese characters might only be legible if the page is interpreted as GB2312.

If you configure your FortiGate unit using other encodings, you may need to switch language settings on your management computer, including for your web browser or Telnet/SSH client. For instructions on how to configure your management computer’s operating system language, locale, or input method, see its documentation.

If you choose to configure parts of the FortiGate unit using non-ASCII characters, verify that all systems interacting with the FortiGate unit also support the same encodings. You should also use the same encoding throughout the configuration if possible in order to avoid needing to switch the language settings of the GUI and your web browser or Telnet/SSH client while you work.

Similarly to input, your web browser or CLI client should normally interpret display output as encoded using UTF-8. If it does not, your configured items may not display correctly in the GUI or CLI. Exceptions include items such as regular expressions that you may have configured using other encodings in order to match the encoding of HTTP requests that the FortiGate unit receives.

To enter non-ASCII characters in the CLI console:
  1. On your management computer, start your web browser and go to the URL for the FortiGate unit’s GUI.
  2. Configure your web browser to interpret the page as UTF-8 encoded.
  3. Log in to the FortiGate unit.
  4. Open the CLI Console from the upper right-hand corner.
  5. In the title bar of the CLI Console widget, click Edit (the pencil icon).
  6. Enable Use external command input box and select OK.
  7. The Command field appears below the usual input and display area of the CLI Console .
  8. Type a command in this field and press Enter.

In the display area, the CLI Console widget displays your previous command interpreted into its character code equivalent, such as:

edit \743\601\613\743\601\652

and the command’s output.

To enter non-ASCII characters in a Telnet/SSH client
  1. On your management computer, start your Telnet or SSH client.
  2. Configure your Telnet or SSH client to send and receive characters using UTF-8 encoding.

    Support for sending and receiving international characters varies by each Telnet/SSH client. Consult the documentation for your Telnet/SSH client.

  3. Log in to the FortiGate unit.
  4. At the command prompt, type your command and press Enter.

    You may need to surround words that use encoded characters with single quotes ( ' ).

    Depending on your Telnet/SSH client’s support for your language’s input methods and for sending international characters, you may need to interpret them into character codes before pressing Enter.

    For example, you might need to enter:

    edit '\743\601\613\743\601\652'

  5. The CLI displays your previous command and its output.

Screen paging

You can configure the CLI to pause after displaying each page’s worth of text when displaying multiple pages of output. When the display pauses, the last line displays ‑‑More‑‑. You can then either:

  • press the spacebar to display the next page.
  • type Q to truncate the output and return to the command prompt.

This may be useful when displaying lengthy output, such as the list of possible matching commands for command completion, or a long list of settings. Rather than scrolling through or possibly exceeding the buffer of your terminal emulator, you can simply display one page at a time.

To configure the CLI Console to pause display when the screen is full:

config system console

set output more

end

Baud rate

You can change the default baud rate of the local console connection.

To change the baud rate enter the following commands:

config system console

set baudrate {9600 | 19200 | 38400 | 57600 | 115200}

end

Editing the configuration file on an external host

You can edit the FortiGate configuration on an external host by first backing up the configuration file to a TFTP server. Then edit the configuration file and restore it to the FortiGate unit.

Editing the configuration on an external host can be timesaving if you have many changes to make, especially if your plain text editor provides advanced features such as batch changes.

To edit the configuration on your computer:
  1. Use execute backup to download the configuration file to a TFTP server, such as your management computer.
  2. Edit the configuration file using a plain text editor that supports Unix-style line endings.

    caution icon

    Do not edit the first line. The first line(s) of the configuration file (preceded by a # character) contains information about the firmware version and FortiGate model. If you change the model number, the FortiGate unit will reject the configuration file when you attempt to restore it.

  3. Use execute restore to upload the modified configuration file back to your FortiGate.

    The FortiGate downloads the configuration file and checks that the model information is correct. If it is correct, the FortiGate unit loads the configuration file and checks each command for errors. If a command is invalid, the FortiGate unit ignores the command. If the configuration file is valid, the FortiGate unit restarts and loads the new configuration.