Fortinet Document Library

Version:


Table of Contents

Cookbook

6.2.0
Download PDF
Copy Link

CLI basics

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

Help

Press the question mark (?) key to display command help and complete commands.

  • Press the question mark (?) key at the command prompt to display a list of the commands available and a description of each command.
  • Enter a command followed by a space and press the question mark (?) key to display a list of the options available for that command and a description of each option.
  • Enter a command followed by an option and press the question mark (?) key to display a list of additional options available for that command option combination and a description of each option.
  • Enter a question mark after entering a portion of a command to see a list of valid complete commands and their descriptions. If there is only one valid command, it will be automatically filled in.

Shortcuts and key commands

Shortcut key Action

?

List valid complete or subsequent commands.

If multiple commands can complete the command, they are listed with their descriptions.

Tab

Complete the word with the next available match.

Press 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, enter a space instead of a backslash, and then press Enter.

Command tree

Enter tree to display the CLI command tree. To capture the full output, connect to your device using a terminal emulation program and capture the output to a log file. For some commands, use the tree command to view all available variables and subcommands.

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 configuring a list, the set command will remove the previous configuration.

For example, if a user group currently includes members A, B, and C, the command set member D will remove members A, B, and C. To avoid removing the existing members from the group, the command set members A B C D must be used.

To avoid this issue, the following commands are available:

append

Add an option to an existing list.

For example, append member D adds user D to the user group without removing any of the existing members.

select

Clear all of the options except for those specified.

For example, select member B removes all member from the group except for member B.

unselect

Remove an option from an existing list.

For example, unselect member C removes only member C from the group, without affecting the other members.

Environment variables

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

$USERFROM

The management access type (ssh, jsconsole, and so on) and the IPv4 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, to set a FortiGate device's host name to its serial number, use the following CLI command:

config system global

set hostname $SerialNum

end

Special characters

The following characters cannot be used in most CLI commands: <, >, (, ), #, ', and "

If one of those characters, or a space, needs to be entered as part of a string, it can be entered by using a special command, enclosing the entire string in quotes, or preceding it with an escape character (backslash, \).

To enter a question mark (?) or a tab, Ctrl + V must be entered first.

Character Keys

?

Ctrl + V then ?

Tab

Ctrl + V then Tab

Space

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

Enclose the string in single or double quotation marks: "Security Administrator”. or 'Security Administrator'.

Precede the space with a backslash: Security\ Administrator.

'

(as part of a string value, not to begin or end the string)

\'

"

(as part of a string value, not to begin or end the string)

\"

\

\\

Using grep to filter command output

The get, show, and diagnose commands can produce large amounts of output. The grep command can be used to filter the output so that it only shows the required information.

The grep command is based on the standard UNIX grep, used for searching text output based on regular expressions.

For example, the following command displays the MAC address of the internal interface:

get hardware nic internal | grep Current_HWaddr
    Current_HWaddr        00:09:0f:cb:c2:75

The following command will display all TCP sessions that are in the session list, including the session list line number in the output:

get system session list | grep -n tcp

The following command will display all of the lines in the HTTP replacement message that contain URL or url:

show system replacemsg http | grep -i url

The following options can also be used:

-A <num> After

-B <num> Before

-C <num> Context

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

Without -f:

show | grep ldap-group1
    edit "ldap-group1"
        set groups "ldap-group1"

With -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

Language support and regular expressions

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

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, 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 a different encoding, or if an HTTP client sends a request in a different encoding, matches may not be what is expected.

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 monetary values with a yen symbol may not work it if the symbol is entered using the wrong encoding.

For best results:

  • use UTF-8 encoding, or
  • use only characters whose numerically encoded values are the same in UTF‑8, such as the US-ASCII characters that are encoded using the same values in ISO 8859-1, Windows code page 1252, Shift-JIS, and other encoding methods, 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 based on the client’s operating system or input language. If the client's encoding method cannot be predicted, you might only be able to match the parts of the request that are in English, as the values for English characters tend to be encoded identically, regardless of the encoding method.

If the FortiGate is configured to use an encoding method other than UTF-8, the management computer's language may need to be changed, including the web browse and terminal emulator. If the FortiGate is configured using non-ASCII characters, all the systems that interact with the FortiGate must also support the same encoding method. If possible, the same encoding method should be used throughout the configuration to avoid needing to change the language settings on the management computer.

The GUI and CLI client normally interpret output as encoded using UTF-8. If they do not, configured items may not display correctly. Exceptions include items such as regular expression that may be configured using other encodings to match the encoding of HTTP requests that the FortiGate receives.

To enter non-ASCII characters in a terminal emulator:
  1. On the management computer, start the terminal client.
  2. Configure the client to send and receive characters using UTF-8 encoding.

    Support for sending and receiving international characters varies by terminal client.

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

    Words that use encoded characters may need to be enclosed in single quotes ( ' ).

    Depending on your terminal client’s language support, you may need to interpret the characters into character codes before pressing Enter. For example, you might need to enter: edit '\743\601\613\743\601\652'

  5. The CLI displays the command and its output.

Screen paging

By default, the CLI will pause after displaying each page worth of text when a command has multiple pages of output. this can be useful when viewing lengthy outputs that might exceed the buffer of terminal emulator.

When the display pauses and shows --More--, you can:

  • Press Enter to show the next line,
  • Press Q to stop showing results and return to the command prompt,
  • Press an arrow key, Insert, Home, Delete, End, Page Up, or Page Down to show the next few pages,
  • Press any other key to show the next page, or
  • Wait for about 30 seconds for the console to truncate the output and return to the command prompt.

When pausing the screen is disable, press Ctrl + C to stop the output and log out of the FortiGate.

To disable pausing the CLI output:

config system console

set output standard

end

To enable pausing the CLI output:

config system console

set output more

end

Changing the baud rate

The baud rate of the local console connection can be changed from its default value of 9600.

To change the baud rate:

config system console

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

end

Editing the configuration file

The FortiGate configuration file can be edited on an external host by backing up the configuration, editing the configuration file, and then restoring the configuration to the FortiGate.

Editing the configuration file can save time is many changes need to be made, particularly if the plain text editor that you are using provides features such as batch changes.

To edit the configuration file:
  1. Backup the configuration. See Configuration backups for details.
  2. Open the configuration file in a plain text editor that supports UNIX-style line endings.
  3. Edit the file as needed.
    Caution

    Do not edit the first line of the configuration file.

    This line contains information about the firmware version and FortiGate model. If you change the model number, the FortiGate unit will reject the configuration when you attempt to restore it.

  4. Restore the modified configuration to the FortiGate. See Configuration backups for details.

    The FortiGate downloads the configuration file and checks that the model information is correct. If it is correct, the configuration file is loaded and each line is checked for errors. If a command is invalid, that command is ignored. If the configuration file is valid, the FortiGate restarts and loads the downloaded configuration.

CLI basics

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

Help

Press the question mark (?) key to display command help and complete commands.

  • Press the question mark (?) key at the command prompt to display a list of the commands available and a description of each command.
  • Enter a command followed by a space and press the question mark (?) key to display a list of the options available for that command and a description of each option.
  • Enter a command followed by an option and press the question mark (?) key to display a list of additional options available for that command option combination and a description of each option.
  • Enter a question mark after entering a portion of a command to see a list of valid complete commands and their descriptions. If there is only one valid command, it will be automatically filled in.

Shortcuts and key commands

Shortcut key Action

?

List valid complete or subsequent commands.

If multiple commands can complete the command, they are listed with their descriptions.

Tab

Complete the word with the next available match.

Press 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, enter a space instead of a backslash, and then press Enter.

Command tree

Enter tree to display the CLI command tree. To capture the full output, connect to your device using a terminal emulation program and capture the output to a log file. For some commands, use the tree command to view all available variables and subcommands.

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 configuring a list, the set command will remove the previous configuration.

For example, if a user group currently includes members A, B, and C, the command set member D will remove members A, B, and C. To avoid removing the existing members from the group, the command set members A B C D must be used.

To avoid this issue, the following commands are available:

append

Add an option to an existing list.

For example, append member D adds user D to the user group without removing any of the existing members.

select

Clear all of the options except for those specified.

For example, select member B removes all member from the group except for member B.

unselect

Remove an option from an existing list.

For example, unselect member C removes only member C from the group, without affecting the other members.

Environment variables

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

$USERFROM

The management access type (ssh, jsconsole, and so on) and the IPv4 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, to set a FortiGate device's host name to its serial number, use the following CLI command:

config system global

set hostname $SerialNum

end

Special characters

The following characters cannot be used in most CLI commands: <, >, (, ), #, ', and "

If one of those characters, or a space, needs to be entered as part of a string, it can be entered by using a special command, enclosing the entire string in quotes, or preceding it with an escape character (backslash, \).

To enter a question mark (?) or a tab, Ctrl + V must be entered first.

Character Keys

?

Ctrl + V then ?

Tab

Ctrl + V then Tab

Space

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

Enclose the string in single or double quotation marks: "Security Administrator”. or 'Security Administrator'.

Precede the space with a backslash: Security\ Administrator.

'

(as part of a string value, not to begin or end the string)

\'

"

(as part of a string value, not to begin or end the string)

\"

\

\\

Using grep to filter command output

The get, show, and diagnose commands can produce large amounts of output. The grep command can be used to filter the output so that it only shows the required information.

The grep command is based on the standard UNIX grep, used for searching text output based on regular expressions.

For example, the following command displays the MAC address of the internal interface:

get hardware nic internal | grep Current_HWaddr
    Current_HWaddr        00:09:0f:cb:c2:75

The following command will display all TCP sessions that are in the session list, including the session list line number in the output:

get system session list | grep -n tcp

The following command will display all of the lines in the HTTP replacement message that contain URL or url:

show system replacemsg http | grep -i url

The following options can also be used:

-A <num> After

-B <num> Before

-C <num> Context

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

Without -f:

show | grep ldap-group1
    edit "ldap-group1"
        set groups "ldap-group1"

With -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

Language support and regular expressions

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

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, 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 a different encoding, or if an HTTP client sends a request in a different encoding, matches may not be what is expected.

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 monetary values with a yen symbol may not work it if the symbol is entered using the wrong encoding.

For best results:

  • use UTF-8 encoding, or
  • use only characters whose numerically encoded values are the same in UTF‑8, such as the US-ASCII characters that are encoded using the same values in ISO 8859-1, Windows code page 1252, Shift-JIS, and other encoding methods, 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 based on the client’s operating system or input language. If the client's encoding method cannot be predicted, you might only be able to match the parts of the request that are in English, as the values for English characters tend to be encoded identically, regardless of the encoding method.

If the FortiGate is configured to use an encoding method other than UTF-8, the management computer's language may need to be changed, including the web browse and terminal emulator. If the FortiGate is configured using non-ASCII characters, all the systems that interact with the FortiGate must also support the same encoding method. If possible, the same encoding method should be used throughout the configuration to avoid needing to change the language settings on the management computer.

The GUI and CLI client normally interpret output as encoded using UTF-8. If they do not, configured items may not display correctly. Exceptions include items such as regular expression that may be configured using other encodings to match the encoding of HTTP requests that the FortiGate receives.

To enter non-ASCII characters in a terminal emulator:
  1. On the management computer, start the terminal client.
  2. Configure the client to send and receive characters using UTF-8 encoding.

    Support for sending and receiving international characters varies by terminal client.

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

    Words that use encoded characters may need to be enclosed in single quotes ( ' ).

    Depending on your terminal client’s language support, you may need to interpret the characters into character codes before pressing Enter. For example, you might need to enter: edit '\743\601\613\743\601\652'

  5. The CLI displays the command and its output.

Screen paging

By default, the CLI will pause after displaying each page worth of text when a command has multiple pages of output. this can be useful when viewing lengthy outputs that might exceed the buffer of terminal emulator.

When the display pauses and shows --More--, you can:

  • Press Enter to show the next line,
  • Press Q to stop showing results and return to the command prompt,
  • Press an arrow key, Insert, Home, Delete, End, Page Up, or Page Down to show the next few pages,
  • Press any other key to show the next page, or
  • Wait for about 30 seconds for the console to truncate the output and return to the command prompt.

When pausing the screen is disable, press Ctrl + C to stop the output and log out of the FortiGate.

To disable pausing the CLI output:

config system console

set output standard

end

To enable pausing the CLI output:

config system console

set output more

end

Changing the baud rate

The baud rate of the local console connection can be changed from its default value of 9600.

To change the baud rate:

config system console

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

end

Editing the configuration file

The FortiGate configuration file can be edited on an external host by backing up the configuration, editing the configuration file, and then restoring the configuration to the FortiGate.

Editing the configuration file can save time is many changes need to be made, particularly if the plain text editor that you are using provides features such as batch changes.

To edit the configuration file:
  1. Backup the configuration. See Configuration backups for details.
  2. Open the configuration file in a plain text editor that supports UNIX-style line endings.
  3. Edit the file as needed.
    Caution

    Do not edit the first line of the configuration file.

    This line contains information about the firmware version and FortiGate model. If you change the model number, the FortiGate unit will reject the configuration when you attempt to restore it.

  4. Restore the modified configuration to the FortiGate. See Configuration backups for details.

    The FortiGate downloads the configuration file and checks that the model information is correct. If it is correct, the configuration file is loaded and each line is checked for errors. If a command is invalid, that command is ignored. If the configuration file is valid, the FortiGate restarts and loads the downloaded configuration.