doc: update srv6 cli guide

Signed-off-by: Hiroki Shirokura <slank.dev@gmail.com>

1 files changed, 75 insertions, 42 deletions

diff --git a/doc/user/zebra.rst b/doc/user/zebra.rst
index 2522ec677..34e102883 100644
--- a/doc/user/zebra.rst
+++ b/doc/user/zebra.rst
@@ -622,7 +622,7 @@ presence of the entry.
 
 .. _zebra-srv6:
 
-Segment-Routing SRv6
+Segment-Routing IPv6
 ====================
 
 Segment-Routing is source routing paradigm that allows
@@ -640,14 +640,12 @@ and this section also helps that case.
 .. index:: show segment-routing srv6 locator [json]
 .. clicmd:: show segment-routing srv6 locator [json]
 
-   This command dump SRv6-locator configured on zebra.
-   SRv6-locator is used to route to the node before performing
-   the SRv6-function. and that works as aggregation of
-   SRv6-function's IDs.
-   Following console log shows two SRv6-locators LOC1 and LOC2.
-   All locators are identified by unique IPv6 prefix.
-   User can get that information as JSON string when ``json``
-   key word at the end of cli is presented.
+   This command dump SRv6-locator configured on zebra.  SRv6-locator is used
+   to route to the node before performing the SRv6-function. and that works as
+   aggregation of SRv6-function's IDs.  Following console log shows two
+   SRv6-locators loc1 and loc2.  All locators are identified by unique IPv6
+   prefix.  User can get that information as JSON string when ``json`` key word
+   at the end of cli is presented.
 
 ::
 
@@ -655,49 +653,84 @@ and this section also helps that case.
    Locator:
    Name                 ID      Prefix                   Status
    -------------------- ------- ------------------------ -------
-   hoge                       1 1::/64                   Up
-   fuga                       2 2::/64                   Up
+   loc1                       1 2001:db8:1:1::/64        Up
+   loc2                       2 2001:db8:2:2::/64        Up
+
+.. index:: show segment-routing srv6 locator NAME detail [json]
+.. clicmd:: show segment-routing srv6 locator NAME detail [json]
+
+   As shown in the example, by specifying the name of the locator, you
+   can see the detailed information for each locator.  Locator can be
+   represented by a single IPv6 prefix, but SRv6 is designed to share this
+   Locator among multiple Routing Protocols. For this purpose, zebra divides
+   the IPv6 prefix block that makes the Locator unique into multiple chunks,
+   and manages the ownership of each chunk.
+
+   For example, loc1 has system as its owner. For example, loc1 is owned by
+   system, which means that it is not yet proprietary to any routing protocol.
+   For example, loc2 has sharp as its owner. This means that the shaprd for
+   function development holds the owner of the chunk of this locator, and no
+   other routing protocol will use this area.
+
+::
+
+   router# show segment-routing srv6 locator loc1 detail
+   Name: loc1
+   Prefix: 2001:db8:1:1::/64
+   Chunks:
+   - prefix: 2001:db8:1:1::/64, owner: system
+
+   router# show segment-routing srv6 locator loc2 detail
+   Name: loc2
+   Prefix: 2001:db8:2:2::/64
+   Chunks:
+   - prefix: 2001:db8:2:2::/64, owner: sharp
 
 .. index:: segment-routing
 .. clicmd:: segment-routing
+
+   Move from configure mode to segment-routing node.
+
 .. index:: srv6
 .. clicmd:: srv6
+
+   Move from segment-routing node to srv6 node.
+
 .. index:: locators
 .. clicmd:: locators
 
-   User can enter the SRv6 configuration node with ``segment-routing`` and
-   ``srv6`` commands in configure mode. If there is some SRv6-locator exist,
-   SRv6 feature is looked enabled and this affects running-config.
-
-   User can enter the Locators node with ``locators`` command
-   in srv6 configure mode.
-   After entering locators node, user can configure one or multi SRv6-locators.
+   Move from srv6 node to locator node. In this locator node, user can
+   configure detailed settings such as the actual srv6 locator.
 
 .. index:: locator NAME
 .. clicmd:: locator NAME
-.. index:: prefix X:X::X:X/M [function-bits-length 32]
-.. clicmd:: prefix X:X::X:X/M [function-bits-length 32]
 
-   Following example console log shows the typical configuration of
-   SRv6 data-plane. After a new SRv6 locator, named LOC1, is created,
-   LOC1's prefix is configured as ``2001:db8:a:a::/64``.
+   Create a new locator. If the name of an existing locator is specified,
+   move to specified locator's configuration node to change the settings it.
 
-   If user or some routing daemon allocates new SID on this locator,
-   new SID will allocated in range of this prefix.
-
-   For example, if some routing daemon creates new SID on locator
-   (``2001:db8:a:a::/64``), Then new SID will be
-   ``2001:db8:a:a:7::/80``, ``2001:db8:a:a:8::/80``, and so on.
-
-   Each locator has default SID that is SRv6 local function "End".
-   Usually default SID is allocated as ``PREFIX:1::``.
-   (``PREFIX`` is locator's prefix)
-   For example, if user configure the locator's prefix as
-   ``2001:db8:a:a::/64``, then default SID will be ``2001:db8:a:a:1::``)
+.. index:: prefix X:X::X:X/M [function-bits-length 32]
+.. clicmd:: prefix X:X::X:X/M [function-bits-length 32]
 
-   The function bits range is 16bits by default.
-   If operator want to change function bits range, they can configure
-   with ``function-bits-length`` option.
+   Set the ipv6 prefix block of the locator. SRv6 locator is defined by
+   RFC8986. The actual routing protocol specifies the locator and allocates a
+   SID to be used by each routing protocol. This SID is included in the locator
+   as an IPv6 prefix.
+
+   Following example console log shows the typical configuration of SRv6
+   data-plane. After a new SRv6 locator, named loc1, is created, loc1's prefix
+   is configured as ``2001:db8:1:1::/64``.  If user or some routing daemon
+   allocates new SID on this locator, new SID will allocated in range of this
+   prefix. For example, if some routing daemon creates new SID on locator
+   (``2001:db8:1:1::/64``), Then new SID will be ``2001:db8:1:1:7::/80``,
+   ``2001:db8:1:1:8::/80``, and so on.  Each locator has default SID that is
+   SRv6 local function "End".  Usually default SID is allocated as
+   ``PREFIX:1::``.  (``PREFIX`` is locator's prefix) For example, if user
+   configure the locator's prefix as ``2001:db8:1:1::/64``, then default SID
+   will be ``2001:db8:1:1:1::``)
+
+   The function bits range is 16bits by default.  If operator want to change
+   function bits range, they can configure with ``function-bits-length``
+   option.
 
 ::
 
@@ -705,16 +738,16 @@ and this section also helps that case.
    router(config)# segment-routinig
    router(config-sr)# srv6
    router(config-srv6)# locators
-   router(config-srv6-locs)# locator LOC1
-   router(config-srv6-loc)# prefix 2001:db8:a:a::/64
+   router(config-srv6-locs)# locator loc1
+   router(config-srv6-loc)# prefix 2001:db8:1:1::/64
 
    router(config-srv6-loc)# show run
    ...
    segment-routing
     srv6
      locators
-      locator LOC1
-       prefix 2001:db8:a:a::/64
+      locator loc1
+       prefix 2001:db8:1:1::/64
       !
    ...