summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Göhler <github@ghlr.de>2024-09-06 21:33:30 +0200
committerGitHub <noreply@github.com>2024-09-06 21:33:30 +0200
commitcbf48f9a18675a9f00982179f97f91c388728c06 (patch)
tree43ec84a6cf542155969f3d1f3519fac9d06bdb18
parentbb3e8db9a53bfcded37aa4f2f78ce0b463589225 (diff)
parent0a98076e88d0df05be43dd7cd90b900858f0d74a (diff)
downloadvyos-documentation-cbf48f9a18675a9f00982179f97f91c388728c06.tar.gz
vyos-documentation-cbf48f9a18675a9f00982179f97f91c388728c06.zip
Merge pull request #1539 from dmbaturin/op-mode-words
cli: Document top-level op mode word meanings
-rw-r--r--docs/cli.rst109
1 files changed, 109 insertions, 0 deletions
diff --git a/docs/cli.rst b/docs/cli.rst
index c1a9d14c..8169cbd5 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -71,6 +71,115 @@ When viewing in page mode the following commands are available:
* ``left-arrow`` and ``right-arrow`` can be used to scroll left or right
in the event that the output has lines which exceed the terminal size.
+Operational mode command families
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many operational mode commands in VyOS are placed in families such as
+``show``, ``clear``, or ``reset``. Every such family has a specific
+meaning to allow the user to guess how the command is going to behave —
+in particular, whether it will be disruptive to the system or not.
+
+Note that this convention was not always followed with perfect
+consistency and some commands may still be in wrong families, so you
+should always check the command help and documentation if you are not
+sure what exactly it does.
+
+clear
+'''''
+
+"Clear" commands are completely non-disruptive to any system operations.
+Generally, they can be used freely without hesitation.
+
+Most often their purpose is to remove or reset various debug and
+diagnostic information such as system logs and packet counters.
+
+Examples:
+
+- ``clear console`` — clears the screen.
+- ``clear interfaces ethernet eth0 counters`` — zeroes packet counters
+ on ``eth0``.
+- ``clear log`` — deletes all system log entries.
+
+reset
+'''''
+
+"Reset" commands can be locally-disruptive. They may, for example,
+terminate a single user session or a session with a dynamic routing
+protocol peer.
+
+They should be used with caution since they may have a significant
+impact on a particular users in the network.
+
+- ``reset pppoe-server username jsmith`` — terminate all PPPoE sessions
+ from user ``jsmith``.
+- ``reset bgp 192.0.2.54`` — terminates the BGP session with neighbor
+ 192.0.2.54.
+- ``reset vpn ipsec site-to-site peer vpn.example.com`` — terminates
+ IPsec tunnels to ``vpn.example.com``.
+
+restart
+'''''''
+
+"Restart" operations may disrupt an entire subsystem. Most often they
+initiate a restart of a server process, which causes it to be
+unavailable for a brief period and resets all the process state.
+
+They should be used with extreme caution.
+
+- ``restart dhcp server`` — restarts the IPv4 DHCP server process (DHCP
+ requests are not served while it is restarting).
+- ``restart ipsec`` — restarts the IPsec process (which forces all
+ sessions and all IPsec process state to reset).
+
+force
+'''''
+
+"Force" commands force the system to perform an action that it might
+perform by itself at a later point.
+
+Examples:
+
+- ``force arp request interface eth1 address 10.3.0.2`` — send a
+ gratuitious ARP request.
+- ``force root-partition-auto-resize`` — grow the root filesystem to
+ the size of the system partition (this is also done on startup, but
+ this command can do it without a reboot).
+
+execute
+'''''''
+
+"Execute" commands are for executing various diagnostic and auxilliary
+actions that the system would never perform by itself.
+
+Examples:
+
+- ``execute wake-on-lan interface <intf> host <MAC>`` — send a
+ Wake-On-LAN packet to a host.
+
+show
+''''
+
+"Show" commands display various system information. They may
+occasionally use a pager for long outputs, that you can quit by pressing
+the Q button. Their output is always finite, however.
+
+Examples:
+
+- ``show system login`` — displays current system users.
+- ``show ip route`` — displays the IPv4 routing table.
+
+monitor
+'''''''
+
+"Monitor" commands initiate various monitoring operations that may
+output information continuously, until terminated with ``Ctrl-C`` or
+disabled.
+
+Examples:
+
+- ``monitor log`` — continuously outputs latest system logs.
+
+
Configuration Mode
##################