############ CLI Overview ############ This chapter presents a brief summary of the **OSDx CLI**. CLI stands for Command Line Interface. The OSDx CLI has many features, including auto-completion, online help, history, etc. It has two modes of operation: * *Operational menu*. In this menu, you can perform some basic network operations (like ping, traceroute, ssh, etc), filesystem operations (copy, remove, show, etc) or monitor/debug system information. * *Configuration menu*. In this menu, you can modify the device configuration. The prompt changes to bold letters and ends with ``#``. .. important:: You can press the TAB key at any time to show a list of available completions for the current editing line. Accessing the CLI ================= First of all, you will need to access the CLI, to do so there are several methods: locally, through the serial port if the device has one; or remotely, through Telnet or, preferably SSH. Once in the OSDx CLI, it will behave equivalently regardless of how it was accessed. Local access ------------ If the device is physically accessible and it has a serial or console port (usually marked as ``CON``), you may access the CLI through it. All OSDx devices use asynchronous serial transfer at 115200 Baud, no parity, with 8 data bits and 1 stop bit (``115200N81``). *Example:* .. code-block:: none osdx login: admin Password: Welcome to Teldat OSDx v3.7.1.3 This system includes free software. Contact Teldat for licenses information and source code. admin@osdx$ Remote access ------------- The CLI is accessible remotely via Telnet or SSH. Although, by default, only SSH is enabled. The default configuration tries to get an IP address through DHCP, in the following examples ``10.215.168.2`` is used. Note that this value depends on the DHCP server. *SSH example:* .. code-block:: none $ ssh admin@10.215.168.2 Warning: Permanently added '10.215.168.2' (ED25519) to the list of known hosts. admin@10.215.168.2's password: Welcome to Teldat OSDx v3.7.1.3 This system includes free software. Contact Teldat for licenses information and source code. admin@osdx$ *Telnet example:* .. code-block:: none $ telnet 10.215.168.2 Trying 10.215.168.2... Connected to 10.215.168.2. Escape character is '^]'. osdx login: admin Password: Last login: Mon Jul 3 09:16:40 UTC 2023 from 10.215.168.1 on pts/0 Welcome to Teldat OSDx v3.7.1.3 This system includes free software. Contact Teldat for licenses information and source code. admin@osdx$ Operational Mode ================ By default, OSDx is in operational mode and, as previously stated, the command prompt displays a ``$``. OSDx features a rich set of operational level commands to retrieve arbitrary information about your running system. One of the most useful commands is :osdx:op:`show version`. This command shows summarized information relative to the device: OS, hardware and system status. .. code-block:: none admin@osdx$ show version OS vendor: Teldat OS name: OSDx OS version: v3.1.1.1 OS Linux kernel: 4.19.181 OS built by: jeknins@daphne OS build date: Mon Sep 20 11:56:22 UTC 2021 OS installation: physical OS boot mode: user License: BASE N-Cores-1 Hardware vendor: innotek GmbH Hardware model: SDE Hardware OEM model: VirtualBox Hardware version: 1.2 Hardware S/N: 0 Hardware UUID: d45cddc3-ecc6-5776-877e-87749826dc82 Hardware architecture: amd64 Hardware fwid: iso Hardware base MAC: 08:00:27:fc:9d:2c Hardware cpu: 1 x Intel(R) Core(TM) i7-9700K CPU @ 3.60GHz (4 cores) Last reboot reason: Performed by user Date: Tue 21 Sep 2021 11:16:00 AM UTC Uptime: 3:12:01 CPU load (1m, 5m, 15m): 0.00 0.00 0.00 CPU usage % (1m): 0.62 Storage usage (kB): 589868/20501072 Memory usage (kB): 297480/2042816 Temperature (ºC): 0 Users logged in: 0 Mode (current/next boot): user/user Hostname: osdx :osdx:op:`interfaces show` can be used to display basic interface status information: .. code-block:: none ----------------------------------------------------------------- Name IP Adress Admin Oper Vrf Description ----------------------------------------------------------------- dum0 fe80::a068:b3ff:fe36:fdb2/64 up up eth0 10.0.0.1/24 up up fe80::a00:27ff:fe24:1aac/64 eth1 down down eth2 down down eth3 192.168.213.18/22 up up fe80::a00:27ff:fec0:ad36/64 lo 127.0.0.1/8 up up ::1/128 The :osdx:op:`poweroff` and :osdx:op:`reboot` commands can be used to power off or reboot the device. :osdx:op:`show running` displays the configuration that is currently active: .. code-block:: none admin@osdx# show running set interfaces ethernet eth0 address 10.0.0.1/24 set interfaces ethernet eth3 address 192.168.213.18/22 set service dns forwarding name-server 192.168.212.3 set service ssh set system login user admin authentication encrypted-password $6$GSjsCj8gHLv$/VcqU6FLi6CT2Oxn0MJQ2C2tqnRDrYKNF8HIYWJp68nvXvPdFccDsT04.WtigUONbKYrgKg8d6rEs8PjljMkH0 To change the current configuration, you need to access the configuration menu. Configuration Mode ================== To configure OSDx, you will need to enter configuration mode, resulting in the command prompt displaying a ``#`` as shown below: .. code-block:: none admin@osdx$ configure admin@osdx# To modify the device configuration, you must use the ``set`` prefix. This is used to add a new configuration path or value in the device configuration. *Example:* .. code-block:: none admin@osdx# set system description MyDescription The following three commands can be used to retrieve the system configuration: * ``show running``: to display the running (or currently active) configuration. * ``show working``: to display the working configuration (including non-commited changes). * ``show changes``: to display differences between the running and working configurations. *Example:* .. code-block:: none admin@osdx# set traffic selector SEL_ICMP rule 1 protocol icmp admin@osdx# set traffic policy DROP_ICMP rule 1 selector SEL_ICMP admin@osdx# set traffic policy DROP_ICMP rule 1 action drop admin@osdx# admin@osdx# show changes set traffic policy DROP_ICMP rule 1 action drop set traffic policy DROP_ICMP rule 1 selector SEL_ICMP set traffic selector SEL_ICMP rule 1 protocol icmp admin@osdx# admin@osdx# commit The ``delete`` command can be used to delete a value or a complete subtree from the configuration. *Example:* .. code-block:: none admin@osdx# delete interfaces ethernet eth0 .. warning:: If you delete an attribute from a node and it was the last one, the whole node is also removed and the delete operation propagates recursively. *Example*: .. code-block:: none admin@osdx# show working path protocols static set protocols static route 10.0.0.0/24 next-hop 192.168.1.1 interface eth0 set protocols static route 10.0.0.0/24 next-hop 192.168.1.2 If you issue the following command: ``del protocols static route 10.0.0.0/24 next-hop 192.168.1.1 interface``, the whole node ``next-hop 192.168.1.1`` will also be deleted since there are no remaining attributes in that node. *Another example:* .. code-block:: none admin@osdx# show working path protocols static set protocols static route 10.0.0.0/24 next-hop 192.168.1.1 interface eth0 If you now issue the same command, the whole ``protocols static`` node subtree will be removed. After every configuration change, you must apply the changes using the following command: .. code-block:: none commit You can type ``discard`` at any time to discard non-committed changes (*working configuration*). These changes can be displayed by issuing a ``show changes`` command. Once your configuration works as expected, you can save it permanently by using the following command: .. code-block:: none save ``exit`` can be used to return to the operational menu. .. tip:: You can run an operational command directly from this menu by using ``run`` followed by the operational command. *Example:* .. code-block:: none admin@osdx# run show interfaces ---------------------------------------------------------------- Name IP Adress Admin Oper Vrf Description ---------------------------------------------------------------- eth0 fe80::a00:27ff:feb7:4644/64 up up eth1 down down eth2 down down eth3 192.168.213.18/22 up up fe80::a00:27ff:fef5:5868/64 lo 127.0.0.1/8 up up ::1/128 Tips and advanced features ========================== In this section, some tips and advanced features are discussed. Keyboard shortcuts ------------------ This is a list of the most frequently used shortcuts in the OSDx CLI: * UP and DOWN arrow keys: navigate between command history. * TAB: show completion for current editing line. * CTRL + A: move to the beginning of the line. * CTRL + B / LEFT arrow key: move back one character. * CTRL + C: stop the currently running command. * CTRL + D: delete one character backward or, if the line is empty, it behaves like the ``exit`` command. * CTRL + E: move to the end of the line. * CTRL + F / RIGHT arrow key: move forward one character. * CTRL + K: delete all characters after the cursor. * CTRL + L: clear the screen and redisplay the line. It behaves like the ``clear console`` operational command. CLI shortcuts ------------- Command abbreviations are allowed as long as the command is not ambiguous. For example, in the operational menu, you can type ``conf`` instead of :osdx:op:`configure` to access the configuration menu. This is a good way to save some time. *Example:* .. code-block:: none admin@osdx$ conf admin@osdx# Besides that, typing the interface type is not necessary. For example, to set an address to the *br0* interface, you could use the ``set interfaces br0 address`` configuration command, instead of using ``set interfaces bridge br0 address``. *Example:* .. code-block:: none admin@osdx# set interfaces br0 address 1.0.0.1/24 admin@osdx# commit Available commands ------------------ Running :osdx:op:`show commands` (in both operational and configuration modes) will give you a list of the available commands. ``path `` can be used to display a specific tree. *Example:* .. code-block:: none admin@DUT0# show commands path interfaces ethernet eth0 traffic policy # Showing all commands available under 'interfaces ethernet eth0 traffic policy' interfaces ethernet eth0 traffic policy in interfaces ethernet eth0 traffic policy local-in interfaces ethernet eth0 traffic policy local-out interfaces ethernet eth0 traffic policy out Pipes ===== Pipes can be used in both operational and configuration menus. In OSDx, a pipe is a special operator that connects the output of one command to the input of another. There are many things you can do using pipes. For example, you can store a command's output, filter its content or measure its execution time. OSDx includes the following pipes: * ``file ``: to save command output to a file. * ``grep [options] ``: to print lines matching a certain pattern. There are some options available, such as: * ``-E``: to interpret as an extended regular expression. * ``-v``: to invert the sense of matching, selecting only non-matching lines. * ``head [options]``: to show the initial part of a command's output. Some available options are: * ``-n ``: to print the first lines (10 are printed by default). * ``less``: to process a command's output. * ``tail [options]``: similar to head but it shows the last part of a command's output. * ``time``: to measure the execution time of a command. * ``wc``: to print new line, word and byte counts. *Example:* .. code-block:: none admin@osdx$ show tech-support | file running://support/2020_september Command's output saved under "support/2020_september" Filesize: 363.719 KB *Example:* .. code-block:: none admin@osdx# commit | time ----------------------- Elapsed time: 2s 353ms.