The simulator reference omitted important startup behavior and several public interfaces, making it difficult to reproduce examples against the current utility. Describe the supported workflow and constraints from the implementation.
Assisted-by: GPT-5.6-Luna, OpenCode Signed-off-by: Ales Musil <[email protected]> --- Documentation/ref/ovn-sim.1.rst | 140 +++++++++++++++++++++++--------- 1 file changed, 100 insertions(+), 40 deletions(-) diff --git a/Documentation/ref/ovn-sim.1.rst b/Documentation/ref/ovn-sim.1.rst index 35abd39b1..211df4922 100644 --- a/Documentation/ref/ovn-sim.1.rst +++ b/Documentation/ref/ovn-sim.1.rst @@ -10,8 +10,8 @@ Synopsis Description =========== -``ovn-sim`` is a wrapper script that adds ovn related commands on -top of ``ovs-sim``. +``ovn-sim`` is a wrapper around ``ovs-sim`` that adds commands for +simulating OVN. ``ovs-sim`` provides a convenient environment for running one or more Open vSwitch instances and related software in a sandboxed simulation environment. @@ -29,8 +29,41 @@ build directory, e.g.:: make utilities/ovn-sim -See documentation on ``ovs-sim`` for info on simulator, including the -parameters you can use. +On startup, ``ovn-sim`` checks that both Open vSwitch and OVN have been +built. It then performs the normal ``ovs-sim`` initialization: it removes +any existing ``sandbox`` directory in the current directory, creates a new +one, installs the built Open vSwitch man pages there, and starts a simulated +Open vSwitch instance named ``main``. The simulation does not require +superuser privileges and should not normally be run with them. + +See ``ovs-sim``\(1) for more information about the sandbox and the Open +vSwitch commands available within it. For example, run ``man ovs-sim`` from +an interactive ``ovn-sim`` shell. + +Command-line Options +==================== + +*script* + Sources *script* into the simulator's Bash shell after initializing the + sandbox. Multiple scripts run in command-line order, and state changes + made by one script are visible to subsequent scripts. If a script fails, + ``ovn-sim`` exits immediately with the same status. + +``-i`` or ``--interactive`` + Starts an interactive Bash shell after running any scripts. An + interactive shell is also started when no scripts are specified. Without + this option, ``ovn-sim`` exits after the specified scripts finish. + +``-h`` or ``--help`` + Prints a brief usage message and exits. + +Commands +======== + +Scripts and interactive sessions can use all commands documented by +``ovs-sim``\(1), including ``sim_add``, ``as``, ``net_add``, and +``net_attach``. They can also use the following OVN-specific commands. The +commands are exported Bash functions, so they are available in scripts. OVN Commands ------------ @@ -39,71 +72,98 @@ These commands interact with OVN, the Open Virtual Network. ``ovn_start`` [*options*] Creates and initializes the central OVN databases (both - ``ovn-sb(5)`` and ``ovn-nb(5)``) and starts an instance of - ``ovsdb-server`` for each one. Also starts an instance of - ``ovn-northd``. + ``ovn-sb``\(5) and ``ovn-nb``\(5)), starts their ``ovsdb-server`` + instances, and starts ``ovn-northd``. It also installs the built OVN man + pages and configures ``ovn-nbctl`` and ``ovn-sbctl`` in the simulation to + use these databases by default. ``ovn_start`` may be run only once in a + simulation. The following options are available: ``--nbdb-model`` *model* - Uses the given database model for the northbound database. - The *model* may be ``standalone`` (the default), ``backup``, - or ``clustered``. + Uses *model* for the northbound database. *model* may be + ``standalone`` (the default), ``backup``, or ``clustered``. + A standalone model starts one server, a backup model starts an + active server and a backup server, and a clustered model starts + the number selected by ``--nbdb-servers``. ``--nbdb-servers`` *n* - For a clustered northbound database, the number of servers in - the cluster. The default is 3. + Selects the clustered model and starts *n* northbound database + servers. *n* must be from 1 through 99. The default for the + clustered model is 3. ``--sbdb-model`` *model* - Uses the given database model for the southbound database. - The *model* may be ``standalone`` (the default), ``backup``, - or ``clustered``. + Uses *model* for the southbound database. *model* may be + ``standalone`` (the default), ``backup``, or ``clustered``. + A standalone model starts one server, a backup model starts an + active server and a backup server, and a clustered model starts + the number selected by ``--sbdb-servers``. ``--sbdb-servers`` *n* - For a clustered southbound database, the number of servers in - the cluster. The default is 3. + Selects the clustered model and starts *n* southbound database + servers. *n* must be from 1 through 99. The default for the + clustered model is 3. + + ``-h`` or ``--help`` + Prints usage information for ``ovn_start``. ``ovn_attach`` *network* *bridge* *ip* [*masklen*] - First, this command attaches bridge to interconnection network - network, just like ``net_attach`` *network* *bridge*. Second, it - configures (simulated) IP address *ip* (with network mask length - *masklen*, which defaults to 24) on *bridge*. Finally, it - configures the Open vSwitch database to work with OVN and starts - ``ovn-controller``. + Attaches *bridge* in the default sandbox to interconnection network + *network*, as with ``net_attach`` *network* *bridge*. It configures the + simulated IPv4 address *ip* on *bridge*, with prefix length *masklen*, + which defaults to 24. IPv6 addresses are not supported. + + The command configures the sandbox to use the southbound database, + configures Geneve encapsulation with *ip* as the encapsulation address, + creates ``br-int``, and starts ``ovn-controller``. Run ``ovn_start`` and + ``net_add`` first, then use ``sim_add`` and ``ovs-vsctl`` to create the + sandbox and *bridge*. The default sandbox must not be ``main``. + + ``ovn_attach --help`` prints usage information for ``ovn_attach``. + +``ovn_as`` *sandbox* [*command* [*arg*]...] + Selects *sandbox* for both OVN and Open vSwitch commands. Without a + *command*, it changes the default sandbox for subsequent commands. With + a *command*, it runs that command in the selected sandbox, as with + ``as`` *sandbox* *command* *arg*..., and leaves the default Open vSwitch + target unchanged. The OVN directory selection remains in effect. This + is useful for commands such as ``ovn-appctl`` that use OVN runtime + directories. Examples ======== -Simulating hypervisors, starting ovn controller (via ovn_attach) and -adding a logical port on each one of them:: +The following example creates two simulated hypervisors, starts an +``ovn-controller`` on each one with ``ovn_attach``, and adds one logical port +per hypervisor:: ovn_start ovn-nbctl ls-add lsw0 net_add n1 for i in 0 1; do sim_add hv$i - as hv$i + ovn_as hv$i ovs-vsctl add-br br-phys - ovn_attach n1 br-phys 192.168.0.`expr $i + 1` + ovn_attach n1 br-phys 192.168.0.$((i + 1)) ovs-vsctl add-port br-int vif$i -- \ set Interface vif$i external-ids:iface-id=lp$i ovn-nbctl lsp-add lsw0 lp$i ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:00:0$i done -Here’s a primitive OVN "scale test" (adjust the scale by changing -``n`` in the first line):: +The following primitive scale test creates a clustered southbound database +and 200 hypervisors. Adjust the scale by changing ``n`` in the first line:: n=200; export n ovn_start --sbdb-model=clustered net_add n1 ovn-nbctl ls-add br0 - for i in `seq $n`; do + for i in $(seq "$n"); do (sim_add hv$i - as hv$i + ovn_as hv$i ovs-vsctl add-br br-phys - y=$(expr $i / 256) - x=$(expr $i % 256) + y=$((i / 256)) + x=$((i % 256)) ovn_attach n1 br-phys 192.168.$y.$x ovs-vsctl add-port br-int vif$i -- \ set Interface vif$i external-ids:iface-id=lp$i) & @@ -112,15 +172,15 @@ Here’s a primitive OVN "scale test" (adjust the scale by changing esac done wait - for i in `seq $n`; do - yy=$(printf %02x $(expr $i / 256)) - xx=$(printf %02x $(expr $i % 256)) + for i in $(seq "$n"); do + yy=$(printf %02x $((i / 256))) + xx=$(printf %02x $((i % 256))) ovn-nbctl lsp-add br0 lp$i ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:$yy:$xx done -When the scale test has finished initializing, you can watch the -logical ports come up with a command like this:: +When the scale test has finished initializing, the following command shows +logical ports that are not yet up:: - watch 'for i in `seq $n`; do \ - if test `ovn-nbctl lsp-get-up lp$i` != up; then echo $i; fi; done' + watch 'for i in $(seq "$n"); do \ + if test "$(ovn-nbctl lsp-get-up lp$i)" != up; then echo $i; fi; done' -- 2.55.0 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
