summaryrefslogtreecommitdiff
path: root/docs/guides/commands/secondary/spp_mirror.rst
blob: 791e22e05f704c8f869a6ac8bda46fcaa366721f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
..  SPDX-License-Identifier: BSD-3-Clause
    Copyright(c) 2010-2014 Intel Corporation

.. _commands_spp_mirror:

spp_mirror
==========

``spp_mirror`` is an implementation of TaaS feature as a SPP secondary process
for port mirroring.

Each of ``spp_mirror`` processes is managed with ``mirror`` command. Because
basic design of ``spp_mirror`` is derived from ``spp_vf``, its commands are
almost similar to ``spp_vf``.

Secondary ID is referred as ``--client-id`` which is given as an argument
while launching ``spp_mirror``. It should be unique among all of secondary
processes including ``spp_nfv`` and others.

``mirror`` command takes an secondary ID and one of sub commands. Secondary ID
and sub command should be separated with delimiter ``;``, or failed to a
command error. Some of sub commands take additional arguments for
configuration of the process or its resource management.

.. code-block:: console

    spp > mirror SEC_ID; SUB_CMD

In this example, ``SEC_ID`` is a secondary ID and ``SUB_CMD`` is one of the
following sub commands. Details of each of sub commands are described in the
next sections.

* status
* component
* port

``spp_mirror`` supports TAB completion. You can complete all of the name
of commands and its arguments. For instance, you find all of sub commands
by pressing TAB after ``mirror SEC_ID;``.

.. code-block:: console

    spp > mirror 1;  # press TAB key
    component      port        status

It tries to complete all of possible arguments. However, ``spp_mirror`` takes
also an arbitrary parameter which cannot be predicted, for example, name of
component. In this cases, ``spp_mirror`` shows capitalized keyword for
indicating it is an arbitrary parameter. Here is an exmaple of ``component``
command to initialize a worker thread. Keyword ``NAME`` should be replaced with
your favorite name for the worker of the role.

.. code-block:: console

    spp > mirror 1; component st  # press TAB key to show args starting 'st'
    start  stop
    spp > mirror 1; component start NAME  # 'NAME' is shown with TAB after start
    spp > mirror 1; component start mr1   # replace 'NAME' with favorite name
    spp > mirror 1; component start mr1   # then, press TAB to show core IDs
    5  6  7

It is another example of replacing keyword. ``port`` is a sub command for
assigning a resource to a worker thread. ``RES_UID`` is replaced with
resource UID which is a combination of port type and its ID such as
``ring:0`` or ``vhost:1`` to assign it as RX port of forwarder ``mr1``.

.. code-block:: console

    spp > mirror 1; port add RES_UID
    spp > mirror 1; port add ring:0 rx mr1

If you are reached to the end of arguments, no candidate keyword is displayed.
It is a completed statement of ``component`` command, and TAB
completion does not work after ``mirror`` because it is ready to run.

.. code-block:: console

    spp > mirror 1; component start mr1 5 mirror
    Succeeded to start component 'mr1' on core:5

It is also completed secondary IDs of ``spp_mirror`` and it is helpful if you run
several ``spp_mirror`` processes.

.. code-block:: console

    spp > mirror  # press TAB after space following 'mirror'
    1;  3;    # you find two spp_mirror processes of sec ID 1, 3

By the way, it is also a case of no candidate keyword is displayed if your
command statement is wrong. You might be encountered an error if you run the
wrong command. Please take care.

.. code-block:: console

    spp > mirror 1; compa  # no candidate shown for wrong command
    Invalid command "compa".


.. _commands_spp_mirror_status:

status
------

Show the information of worker threads and its resources. Status information
consists of three parts.

.. code-block:: console

    spp > mirror 1; status
    Basic Information:
      - client-id: 3
      - ports: [phy:0, phy:1, ring:0, ring:1, ring:2, ring:3, ring:4]
     - lcore_ids:
       - master: 1
       - slaves: [2, 3, 4]
    Components:
      - core:5 'mr1' (type: mirror)
        - rx: ring:0
        - tx: [ring:1, ring:2]
      - core:6 'mr2' (type: mirror)
        - rx: ring:3
        - tx: [ring:4, ring:5]
      - core:7 '' (type: unuse)

``Basic Information`` is for describing attributes of ``spp_mirror`` itself.
``client-id`` is a secondary ID of the process and ``ports`` is a list of
all of ports owned the process.

``Components`` is a list of all of worker threads. Each of workers has a
core ID running on, type of the worker and a list of resources.
Entry of no name with ``unuse`` type means that no worker thread assigned to
the core. In other words, it is ready to be assinged.


.. _commands_spp_mirror_component:

component
---------

Assing or release a role of forwarding to worker threads running on each of
cores which are reserved with ``-c`` or ``-l`` option while launching
``spp_mirror``. Unlike ``spp_vf``, ``spp_mirror`` only has one role, ``mirror``.

.. code-block:: console

    # assign 'ROLE' to worker on 'CORE_ID' with a 'NAME'
    spp > mirror SEC_ID; component start NAME CORE_ID ROLE

    # release worker 'NAME' from the role
    spp > mirror SEC_ID; component stop NAME

Here is an example of assigning role with ``component`` command.

.. code-block:: console

    # assign 'mirror' role with name 'mr1' on core 2
    spp > mirror 2; component start mr1 2 mirror

And an examples of releasing role.

.. code-block:: console

    # release mirror role
    spp > mirror 2; component stop mr1


.. _commands_spp_mirror_port:

port
----

Add or delete a port to a worker.

Adding port
~~~~~~~~~~~

.. code-block:: console

    spp > mirror SEC_ID; port add RES_UID DIR NAME

``RES_UID`` is with replaced with resource UID such as ``ring:0`` or
``vhost:1``. ``spp_mirror`` supports three types of port.

  * ``phy`` : Physical NIC
  * ``ring`` : Ring PMD
  * ``vhost`` : Vhost PMD

``DIR`` means the direction of forwarding and it should be ``rx`` or ``tx``.
``NAME`` is the same as for ``component`` command.

This is an example for adding ports to ``mr1``. In this case, it is configured
to receive packets from ``ring:0`` and send it to ``vhost:0`` and ``vhost:1``
by duplicating the packets.

.. code-block:: console

    # recieve from 'phy:0'
    spp > mirror 2; port add ring:0 rx mr1

    # send to 'ring:0' and 'ring:1'
    spp > mirror 2; port add vhost:0 tx mr1
    spp > mirror 2; port add vhost:1 tx mr1

Adding port may cause component to start packet forwarding. Please see
details in
:ref:`design spp_mirror<spp_design_spp_sec_mirror>`.

Until one rx and two tx ports are registered, ``spp_mirror`` does not start
forwarding. If it is requested to add more than one rx and two tx ports, it
replies an error message.

Deleting port
~~~~~~~~~~~~~

Delete a port which is not be used anymore. It is almost same as adding port.

.. code-block:: console

    spp > mirror SEC_ID; port del RES_UID DIR NAME


Here is some examples.

.. code-block:: console

    # delete rx port 'ring:0' from 'mr1'
    spp > mirror 2; port del ring:0 rx mr1

    # delete tx port 'vhost:1' from 'mr1'
    spp > mirror 2; port del vhost:1 tx mr1


.. note::

  Deleting port may cause component to stop packet forwarding.
  Please see detail in :ref:`design spp_mirror<spp_design_spp_sec_mirror>`.

exit
----

Terminate ``spp_mirror`` process.

.. code-block:: console

    spp > mirror 2; exit