[patch mlxsw.wiki] ACLs: extend chains section for explicit creation and deletion and add templates section

[Ido Schimmel]

On Tue, Jul 24, 2018 at 02:03:26PM +0200, Jiri Pirko wrote:
> From: Jiri Pirko <jiri at mellanox.com>
> 
> Signed-off-by: Jiri Pirko <jiri at mellanox.com>
> ---
>  ACLs.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---

Need to update 4.19 features as well

>  1 file changed, 78 insertions(+), 3 deletions(-)
> 
> diff --git a/ACLs.md b/ACLs.md
> index 794d29cecdc6..8cd274d004ca 100644
> --- a/ACLs.md
> +++ b/ACLs.md
> @@ -6,9 +6,10 @@
>      4. [Pass Action Example Usage](#pass-action-example-usage)
>      5. [Trap Action Example Usage](#trap-action-example-usage)
>      6. [Multi-table/Multi-chain Support](#multi-tablemulti-chain-support)
> -    7. [Mirred Action Example Usage](#mirred-action-example-usage)
> -    8. [Shared Blocks Support](#shared-blocks-support)
> -    9. [More Examples](#more-examples)
> +    7. [Chain Templates Support](#chain-templates-support)
> +    8. [Mirred Action Example Usage](#mirred-action-example-usage)
> +    9. [Shared Blocks Support](#shared-blocks-support)
> +   10. [More Examples](#more-examples)
>  2. [Further Resources](#further-resources)
>  
>  TC Flower
> @@ -151,6 +152,80 @@ to use the action `goto chain`:
>  $ tc filter add dev enp3s0np1 parent ffff: protocol ip pref 10 flower skip_sw dst_ip 192.168.101.1 action goto chain 100
>  ```
>  
> +If chain does not exist before the filter addition, it is implicitly created.

If a chain does not exist before a filter is added, it is implicitly
created.


> +Also, after the last filter is removed, implicitly created chain is destroyed.

s/Also/Similarly/

Question: If I explicitly create a chain and then remove all the filters
from it, it'll continue to exist? Sounds like it should, but I'm not
sure that's the case.

> +However, if user wants, he can explicitly create or destroy chain.

However, it is possible to explicitly create and destroy chains.

> +
> +To create `chain 11`, one has to run following command:

To create `chain 11`, run the following command:

> +
> +```
> +$ tc chain add dev enp3s0np1 ingress chain 11
> +```
> +
> +If you list the existing commands now, you will see newly created `chain 11` in the output:

To list existing chains, run:

> +
> +```
> +$ tc chain show dev enp3s0np1 ingress
> +chain parent ffff: chain 11
> +```
> +
> +And you can destroy the chain by running following command:
> +
> +```
> +$ tc chain del dev enp3s0np1 ingress chain 11
> +```
> +
> +Note that this will delete both implicitly and explicitly created chains along
> +with any possible existing filters.

Better to use:

**Note:** The above command will ...

> +
> +#### Chain Templates Support
> +
> +For filter insertions to chains, the driver needs to hold a magic ball.

the `mlxsw` driver

> +With the first inserted rule into HW it needs to guess all the fields that

s/HW/hardware/

> +are going to be used for the matching. If later on this guess proves

for the matching in the chain.

> +to be wrong and user adds a filter with a different field to match,

with different fields,

> +there's a problem. `mlxsw' resolves it now with couple of predefined

there is

s/'/`/

tries to resolve it with a couple of

> +patterns. Those try to cover as many match fields as possible.
> +This approach is far from optimal, both performance-wise and
> +scale-wise. Also, there are combinations of filters that in
> +certain order won't succeed to be inserted.

Also, the insertion of certain filters might fail, depending on the
insertion order.

> +
> +Most of the time, when user inserts filters in chain, he knows
> +how the filters are going to look like in advance - what type and
> +option will they have. For example, he knows that he will only
> +insert filters of type flower matching destination IP address.

For example, it is possible that the user knows that only filters of
type flower matching on destination IP are required.

(Try to avoid using 'he')

> +He can specify a template that would cover all the filters he is

s/He/The user/

> +going to insert in the chain.
> +
> +The template is passed along during the chain creation like this:
> +
> +```
> +$ tc chain add dev enp3s0np1 ingress proto ip chain 11 flower dst_ip 0.0.0.0/16
> +```
> +
> +The template is then shown in an output of chain list:
> +
> +```
> +$ tc chain show dev enp3s0np1 ingress
> +chain parent ffff: flower chain 11
> +  eth_type ipv4
> +  dst_ip 0.0.0.0/16
> +```
> +
> +Addition of a filter that fits the template will be successful:

Addition of filters that fit

> +
> +```
> +$ tc filter add dev enp3s0np1 ingress proto ip chain 11 flower dst_ip 10.0.0.1/8 action drop
> +```
> +
> +Addition of filters that does not fit the template would fail:

s/would/will/

> +
> +```
> +$ tc filter add dev enp3s0np1 ingress proto ip chain 11 flower dst_ip 10.0.0.1/24 action drop
> +Error: cls_flower: Mask does not fit the template.
> +We have an error talking to the kernel, -1
> +```

Worth mentioning that insertion of filters that are _contained_ in the
template would also succeed. For example, dst_ip/8.

> +
>  #### Mirred Action Example Usage
>  
>  ```
> -- 
> 2.17.0
>