From e634e945e915a366e67f56f074aadcfc83fccb17 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Thu, 6 Nov 2025 15:33:52 +0100 Subject: [PATCH] =?UTF-8?q?doc:=20shorten=20ps1=20in=20examples=20with=20?= =?UTF-8?q?=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Many of the example prompts used in the documentation are very long and do not fit in generated documentation (web/pdf). This is a proposal to shorten them, sometimes significantly, by keeping only the start and end of an xpath, replacing everything in between with '/…/'. This is a feature that also could be added to the klish-plugin-sysrepo to improve usability. Signed-off-by: Joachim Wiberg --- doc/dhcp.md | 27 +++++++++--------- doc/firewall.md | 72 +++++++++++++++++++++++------------------------ doc/networking.md | 54 +++++++++++++++++------------------ doc/syslog.md | 31 ++++++++++---------- doc/wifi.md | 6 ++-- 5 files changed, 94 insertions(+), 96 deletions(-) diff --git a/doc/dhcp.md b/doc/dhcp.md index 8ebf9d4a..f0444215 100644 --- a/doc/dhcp.md +++ b/doc/dhcp.md @@ -21,10 +21,9 @@ with an address pool: ``` admin@example:/> configure -admin@example:/config/> edit dhcp-server -admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave +admin@example:/config/> edit dhcp-server subnet 192.168.2.0/24 +admin@example:/config/dhcp-server/…/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200 +admin@example:/config/dhcp-server/…/192.168.2.0/24/> leave ``` When setting up the server from the CLI, the system automatically adds a @@ -70,21 +69,21 @@ To reserve specific IP addresses for clients based on their MAC address, hostname, or client ID: ``` -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit host 192.168.2.10 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/host/192.168.2.10/> set match mac-address 00:11:22:33:44:55 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/host/192.168.2.10/> set hostname printer -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/host/192.168.2.10/> leave +admin@example:/config/dhcp-server/…/192.168.2.0/24/> edit host 192.168.2.10 +admin@example:/config/dhcp-server/…/192.168.2.10/> set match mac-address 00:11:22:33:44:55 +admin@example:/config/dhcp-server/…/192.168.2.10/> set hostname printer +admin@example:/config/dhcp-server/…/192.168.2.10/> leave ``` Match hosts using a client identifier instead of MAC address: ``` -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> edit host 192.168.1.50 -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/> edit match -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/match/> set client-id hex c0:ff:ee -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/match/> leave -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/> set lease-time infinite -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/> leave +admin@example:/config/dhcp-server/…/192.168.1.0/24/> edit host 192.168.1.50 +admin@example:/config/dhcp-server/…/192.168.1.50/> edit match +admin@example:/config/dhcp-server/…/match/> set client-id hex c0:ff:ee +admin@example:/config/dhcp-server/…/match/> leave +admin@example:/config/dhcp-server/…/192.168.1.50/> set lease-time infinite +admin@example:/config/dhcp-server/…/192.168.1.50/> leave ``` The `hex` prefix here ensures matching of client ID is done using the diff --git a/doc/firewall.md b/doc/firewall.md index 7c6ba5c9..cef5b7ae 100644 --- a/doc/firewall.md +++ b/doc/firewall.md @@ -289,25 +289,25 @@ blocks external threats. admin@example:/config/> edit firewall admin@example:/config/firewall/> set default wan admin@example:/config/firewall/> edit zone lan -admin@example:/config/firewall/zone/lan/> set description "Internal LAN network - trusted" -admin@example:/config/firewall/zone/lan/> set action accept -admin@example:/config/firewall/zone/lan/> set interface eth1 -admin@example:/config/firewall/zone/lan/> set service ssh -admin@example:/config/firewall/zone/lan/> set service dhcp -admin@example:/config/firewall/zone/lan/> set service dns -admin@example:/config/firewall/zone/lan/> end +admin@example:/config/firewall/…/lan/> set description "Internal LAN network - trusted" +admin@example:/config/firewall/…/lan/> set action accept +admin@example:/config/firewall/…/lan/> set interface eth1 +admin@example:/config/firewall/…/lan/> set service ssh +admin@example:/config/firewall/…/lan/> set service dhcp +admin@example:/config/firewall/…/lan/> set service dns +admin@example:/config/firewall/…/lan/> end admin@example:/config/firewall/> edit zone wan -admin@example:/config/firewall/zone/wan/> set description "External WAN interface - untrusted" -admin@example:/config/firewall/zone/wan/> set action drop -admin@example:/config/firewall/zone/wan/> set interface eth0 -admin@example:/config/firewall/zone/wan/> end +admin@example:/config/firewall/…/wan/> set description "External WAN interface - untrusted" +admin@example:/config/firewall/…/wan/> set action drop +admin@example:/config/firewall/…/wan/> set interface eth0 +admin@example:/config/firewall/…/wan/> end admin@example:/config/firewall/> edit policy loc-to-wan -admin@example:/config/firewall/policy/loc-to-wan/> set description "Allow LAN traffic to WAN with SNAT" -admin@example:/config/firewall/policy/loc-to-wan/> set ingress lan -admin@example:/config/firewall/policy/loc-to-wan/> set egress wan -admin@example:/config/firewall/policy/loc-to-wan/> set action accept -admin@example:/config/firewall/policy/loc-to-wan/> set masquerade -admin@example:/config/firewall/policy/loc-to-wan/> leave +admin@example:/config/firewall/…/loc-to-wan/> set description "Allow LAN traffic to WAN with SNAT" +admin@example:/config/firewall/…/loc-to-wan/> set ingress lan +admin@example:/config/firewall/…/loc-to-wan/> set egress wan +admin@example:/config/firewall/…/loc-to-wan/> set action accept +admin@example:/config/firewall/…/loc-to-wan/> set masquerade +admin@example:/config/firewall/…/loc-to-wan/> leave ### Enterprise Gateway @@ -317,28 +317,28 @@ resources. We can build upon the Home/Office Router example above and add a DMZ zone with additional policies for controlled access. 
admin@example:/> configure
 admin@example:/config/> edit firewall zone dmz
-admin@example:/config/firewall/zone/dmz/> set description "Semi-trusted public services"
-admin@example:/config/firewall/zone/dmz/> set action drop
-admin@example:/config/firewall/zone/dmz/> set interface eth1
-admin@example:/config/firewall/zone/dmz/> set service ssh
-admin@example:/config/firewall/zone/dmz/> end
+admin@example:/config/firewall/…/dmz/> set description "Semi-trusted public services"
+admin@example:/config/firewall/…/dmz/> set action drop
+admin@example:/config/firewall/…/dmz/> set interface eth1
+admin@example:/config/firewall/…/dmz/> set service ssh
+admin@example:/config/firewall/…/dmz/> end
 admin@example:/config/firewall/> edit policy loc-to-wan
-admin@example:/config/firewall/policy/loc-to-wan/> set description "Allow local networks (LAN+DMZ) to WAN with SNAT"
-admin@example:/config/firewall/policy/loc-to-wan/> set ingress dmz
-admin@example:/config/firewall/policy/loc-to-wan/> set egress wan
-admin@example:/config/firewall/policy/loc-to-wan/> set action accept
-admin@example:/config/firewall/policy/loc-to-wan/> set masquerade
-admin@example:/config/firewall/policy/loc-to-wan/> end
+admin@example:/config/firewall/…/loc-to-wan/> set description "Allow local networks (LAN+DMZ) to WAN with SNAT"
+admin@example:/config/firewall/…/loc-to-wan/> set ingress dmz
+admin@example:/config/firewall/…/loc-to-wan/> set egress wan
+admin@example:/config/firewall/…/loc-to-wan/> set action accept
+admin@example:/config/firewall/…/loc-to-wan/> set masquerade
+admin@example:/config/firewall/…/loc-to-wan/> end
 admin@example:/config/firewall/> edit policy lan-to-dmz
-admin@example:/config/firewall/policy/lan-to-dmz/> set description "Allow LAN to manage DMZ services"
-admin@example:/config/firewall/policy/lan-to-dmz/> set ingress lan
-admin@example:/config/firewall/policy/lan-to-dmz/> set egress dmz
-admin@example:/config/firewall/policy/lan-to-dmz/> set action accept
-admin@example:/config/firewall/policy/lan-to-dmz/> end
+admin@example:/config/firewall/…/lan-to-dmz/> set description "Allow LAN to manage DMZ services"
+admin@example:/config/firewall/…/lan-to-dmz/> set ingress lan
+admin@example:/config/firewall/…/lan-to-dmz/> set egress dmz
+admin@example:/config/firewall/…/lan-to-dmz/> set action accept
+admin@example:/config/firewall/…/lan-to-dmz/> end
 admin@example:/config/firewall/> edit zone wan port-forward 8080 tcp
-admin@example:/config/firewall/zone/wan/port-forward/8080/tcp/> set to addr 192.168.2.10
-admin@example:/config/firewall/zone/wan/port-forward/8080/tcp/> set to port 80
-admin@example:/config/firewall/zone/wan/port-forward/8080/tcp/> leave
+admin@example:/config/firewall/…/tcp/> set to addr 192.168.2.10
+admin@example:/config/firewall/…/tcp/> set to port 80
+admin@example:/config/firewall/…/tcp/> leave
This adds a DMZ zone for public services, updates the internet access policy diff --git a/doc/networking.md b/doc/networking.md index 64e0d7d5..bc738812 100644 --- a/doc/networking.md +++ b/doc/networking.md @@ -1264,18 +1264,18 @@ control plane protocol. For our examples we use the instance name For a route with destination 192.168.200.0/24 via 192.168.1.1: admin@example:/> configure - admin@example:/config/> edit routing control-plane-protocol static name default - admin@example:/config/routing/control-plane-protocol/static/name/default/> set ipv4 route 192.168.200.0/24 next-hop next-hop-address 192.168.1.1 - admin@example:/config/routing/control-plane-protocol/static/name/default/> leave + admin@example:/config/> edit routing control-plane-protocol static name default ipv4 + admin@example:/config/routing/…/ipv4/> set route 192.168.200.0/24 next-hop next-hop-address 192.168.1.1 + admin@example:/config/routing/…/ipv4/> leave admin@example:/> For a "floating" static route with destination 10.0.0.0/16 via a backup router 192.168.1.1, using the highest possible distance: admin@example:/> configure - admin@example:/config/> edit routing control-plane-protocol static name default - admin@example:/config/routing/control-plane-protocol/static/name/default/> set ipv4 route 10.0.0.0/16 next-hop next-hop-address 192.168.1.1 route-preference 254 - admin@example:/config/routing/control-plane-protocol/static/name/default/> leave + admin@example:/config/> edit routing control-plane-protocol static name default ipv4 + admin@example:/config/routing/…/ipv4/> set route 10.0.0.0/16 next-hop next-hop-address 192.168.1.1 route-preference 254 + admin@example:/config/routing/…/ipv4/> leave admin@example:/> > [!TIP] @@ -1286,9 +1286,9 @@ router 192.168.1.1, using the highest possible distance: ### IPv6 Static routes admin@example:/> configure - admin@example:/config/> edit routing control-plane-protocol static name default - admin@example:/config/routing/control-plane-protocol/static/name/default/> set ipv6 route 2001:db8:3c4d:200::/64 next-hop next-hop-address 2001:db8:3c4d:1::1 - admin@example:/config/routing/control-plane-protocol/static/name/default/> leave + admin@example:/config/> edit routing control-plane-protocol static name default ipv6 + admin@example:/config/routing/…/ipv6/> set route 2001:db8:3c4d:200::/64 next-hop next-hop-address 2001:db8:3c4d:1::1 + admin@example:/config/routing/…/ipv6/> leave admin@example:/> @@ -1297,9 +1297,9 @@ router 192.168.1.1, using the highest possible distance: The system supports OSPF dynamic routing for IPv4, i.e., OSPFv2. To enable OSPF and set one active interface in area 0: - admin@example:/config/> edit routing control-plane-protocol ospfv2 name default - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> set ospf area 0.0.0.0 interface e0 enabled - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> leave + admin@example:/config/> edit routing control-plane-protocol ospfv2 name default ospf + admin@example:/config/routing/…/ospf/> set area 0.0.0.0 interface e0 enabled + admin@example:/config/routing/…/ospf/> leave admin@example:/> > [!TIP] @@ -1312,10 +1312,10 @@ enable OSPF and set one active interface in area 0: In addition to *regular* OSPF areas, area types *NSSA* and *Stub* are also supported. To configure an NSSA area with summary routes: - admin@example:/config/> edit routing control-plane-protocol ospfv2 name default - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> set ospf area 0.0.0.1 area-type nssa-area - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> set ospf area 0.0.0.1 summary true - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> leave + admin@example:/config/> edit routing control-plane-protocol ospfv2 name default ospf + admin@example:/config/routing/…/ospf/> set area 0.0.0.1 area-type nssa-area + admin@example:/config/routing/…/ospf/> set area 0.0.0.1 summary true + admin@example:/config/routing/…/ospf/> leave admin@example:/> @@ -1324,9 +1324,9 @@ also supported. To configure an NSSA area with summary routes: It is possible to enable BFD per OSPF interface to speed up detection of link loss. - admin@example:/config/> edit routing control-plane-protocol ospfv2 name default - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/> set area 0.0.0.0 interface e0 bfd enabled true - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> leave + admin@example:/config/> edit routing control-plane-protocol ospfv2 name default ospf + admin@example:/config/routing/…/ospf/> set area 0.0.0.0 interface e0 bfd enabled true + admin@example:/config/routing/…/ospf/> leave admin@example:/> @@ -1337,9 +1337,9 @@ and BFD for OSPF per interface (*bfd enabled true*). These and other OSPF interface settings are done in context of an OSFP area, e.g., *area 0.0.0.0*. Available commands can be listed using the `?` mark. - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/> edit ospf area 0.0.0.0 - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/area/0.0.0.0/> edit interface e0 - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/area/0.0.0.0/interface/e0/> set ? + admin@example:/config/routing/…/> edit ospf area 0.0.0.0 + admin@example:/config/routing/…/ospf/area/0.0.0.0/> edit interface e0 + admin@example:/config/routing/…/ospf/area/0.0.0.0/interface/e0/> set ? bfd BFD interface configuration. cost Interface's cost. dead-interval Interval after which a neighbor is declared down @@ -1349,13 +1349,13 @@ OSPF interface settings are done in context of an OSFP area, e.g., *area passive Enables/disables a passive interface. A passive retransmit-interval Interval between retransmitting unacknowledged Link transmit-delay Estimated time needed to transmit Link State Update - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/area/0.0.0.0/interface/e0/> set + admin@example:/config/routing/…/ospf/area/0.0.0.0/interface/e0/> set For example, setting the OSPF *interface type* to *point-to-point* for an Ethernet interface can be done as follows. - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/area/0.0.0.0/interface/e0/> set interface-type point-to-point - admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/area/0.0.0.0/interface/e0/> + admin@example:/config/routing/…/ospf/area/0.0.0.0/interface/e0/> set interface-type point-to-point + admin@example:/config/routing/…/ospf/area/0.0.0.0/interface/e0/> #### OSPF global settings @@ -1364,12 +1364,12 @@ global settings for route redistribution and OSPF router identifier. ``` admin@example:/config/> edit routing control-plane-protocol ospfv2 name default ospf -admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/> set ? +admin@example:/config/routing/…/ospf/> set ? area List of OSPF areas. default-route-advertise Distribute default route to network explicit-router-id Defined in RFC 2328. A 32-bit number redistribute Redistribute protocols into OSPF -admin@example:/config/routing/control-plane-protocol/ospfv2/name/default/ospf/> set +admin@example:/config/routing/…/ospf/> set ``` - Explicit router ID: By default the router will pick an IP address diff --git a/doc/syslog.md b/doc/syslog.md index 3244351d..33cf0375 100644 --- a/doc/syslog.md +++ b/doc/syslog.md @@ -23,17 +23,16 @@ For a list of available log facilities, see the table in a later section. ``` admin@example:/> configure -admin@example:/config/> edit syslog -admin@example:/config/syslog/> edit actions log-file file:/media/log/mylog -admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list +admin@example:/config/> edit syslog actions log-file file:/media/log/mylog +admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all audit auth authpriv console cron cron2 daemon ftp kern local0 local1 local2 local3 local4 local5 local6 local7 lpr mail news ntp syslog user uucp -admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list all severity +admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all severity alert all critical debug emergency error info none notice warning -admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list all severity critical -admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list mail severity warning -admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> leave +admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all severity critical +admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list mail severity warning +admin@example:/config/syslog/…/file:/media/log/mylog/> leave admin@example:/> ``` @@ -137,11 +136,11 @@ perform time stamping at the time of arrival. Configuring the log format is the same for log files and remotes: ``` -admin@example:/config/> edit syslog actions log-file file:foobar -admin@example:/config/syslog/actions/log-file/file:foobar/> set log-format +admin@example:/config/> edit syslog actions log-file file:foobar +admin@example:/config/syslog/…/file:foobar/> set log-format bsd rfc3164 rfc5424 -admin@example:/config/syslog/actions/log-file/file:foobar/> set log-format rfc5424 -admin@example:/config/syslog/actions/log-file/file:foobar/> leave +admin@example:/config/syslog/…/file:foobar/> set log-format rfc5424 +admin@example:/config/syslog/…/file:foobar/> leave admin@example:/> ``` @@ -163,13 +162,13 @@ up, as well as local policy. admin@example:/config/> edit syslog actions file-rotation server admin@example:/config/> edit syslog actions destination moon -admin@example:/config/syslog/actions/destination/moon/> set +admin@example:/config/syslog/…/moon/> set facility-list log-format udp -admin@example:/config/syslog/actions/destination/moon/> set udp +admin@example:/config/syslog/…/moon/> set udp address port -admin@example:/config/syslog/actions/destination/moon/> set udp address 192.168.0.12 -admin@example:/config/syslog/actions/destination/moon/> set facility-list container severity all -admin@example:/config/syslog/actions/destination/moon/> leave +admin@example:/config/syslog/…/moon/> set udp address 192.168.0.12 +admin@example:/config/syslog/…/moon/> set facility-list container severity all +admin@example:/config/syslog/…/moon/> leave admin@example:/> ``` diff --git a/doc/wifi.md b/doc/wifi.md index be5574b3..60dfbe65 100644 --- a/doc/wifi.md +++ b/doc/wifi.md @@ -83,9 +83,9 @@ and 63 characters ``` admin@example:/> configure admin@example:/config/> edit keystore symmetric-key example -admin@example:/config/keystore/symmetric-key/example/> set key-format wifi-preshared-key-format -admin@example:/config/keystore/symmetric-key/example/> set cleartext-key mysecret -admin@example:/config/keystore/symmetric-key/example/> leave +admin@example:/config/keystore/…/example/> set key-format wifi-preshared-key-format +admin@example:/config/keystore/…/example/> set cleartext-key mysecret +admin@example:/config/keystore/…/example/> leave admin@example:/> ```