<commit_before># Configuration

The lwAFTR's configuration is modelled by a
[YANG](https://tools.ietf.org/html/rfc6020) schema,
[snabb-softwire-v1](../../../lib/yang/snabb-softwire-v1.yang).

The lwAFTR takes its configuration from the user in the form of a text
file.  That file's grammar is derived from the YANG schema; see the
[Snabb YANG README](../../../lib/yang/README.md) for full details.
Here's an example:

```
// IPv4 interface.
external-interface {
  allow-incoming-icmp true;
  // Limit ICMP error transmit rate to PACKETS/PERIOD.
  error-rate-limiting {
    packets 600000;
    period 2;
  }
  // Generate ICMP errors at all?
  generate-icmp-errors true;
  // Basic parameters.
  ip 10.10.10.10;
  mac 12:12:12:12:12:12;
  mtu 1460;
  // vlan-tag 42;
  // Where to go next.  Either one will suffice; if you specify the IP,
  // the next-hop MAC will be determined by ARP.
  next-hop {
    mac 68:68:68:68:68:68;
    ip 1.2.3.4;
  }
  // Control the size of the fragment reassembly buffer.
  reassembly {
    max-fragments-per-packet 40;
    max-packets 20000;
  }
}
// The same thing as for the external interface, but on the IPv6 side
// and with IPv6 addresses.
internal-interface {
  allow-incoming-icmp true;
  error-rate-limiting {
    packets 600000;
    period 2;
  }
  generate-icmp-errors true;
  // One more interesting thing -- here we control whether to support
  // routing traffic between two B4s.
  hairpinning true;
  ip 8:9:a:b:c:d:e:f;
  mac 22:22:22:22:22:22;
  mtu 1500;
  // vlan-tag 64;
  next-hop {
    mac 44:44:44:44:44:44;
    // NDP instead of ARP of course.
    ip 7:8:9:a:b:c:d:e;
  }
  reassembly {
    max-fragments-per-packet 40;
    max-packets 20000;
  }
}
// Now the binding table!  3 parts: PSID map, BR address table, and
// softwire set.  See description below for details.
binding-table {
  psid-map { addr 172.16.17.32; psid-length 4; }
  psid-map { addr 172.16.31.10; psid-length 16; }
  psid-map { addr 192.168.3.11; psid-length 16; }
  br-address 8:9:a:b:c:d:e:f;
  br-address fc00:db20:35b:7399::5;
  br-address fd00:c2b6:b24b:be67:2827:688d:e6a1:6a3b;
  softwire {
    ipv4 172.16.31.10;
    psid 22788;
    b4-ipv6 fc00:db20:35b:7399::5;
  }
  softwire {
    ipv4 172.16.31.10;
    psid 2700;
    b4-ipv6 fc00:db20:35b:7399::5;
  }
  softwire {
    ipv4 172.16.17.32;
    psid 1;
    b4-ipv6 fc00:e968:6179::de52:7100;
  }
  softwire {
    ipv4 192.168.3.11;
    psid 7850;
    b4-ipv6 fc00:e968:6179::de52:7100;
    br 1;
  }
}
```

Basically there's an `external-interface` section defining the
parameters around the IPv4 interface that communicates with the
internet, an `internal-interface` section doing the same for the IPv6
side that communicates with the B4s, and then the `binding-table` that
declares the set of softwires.

## Compiling conigurations

When a lwAFTR is started, it will automatically compile its
configuration if it does not find a compiled configuration that's fresh.
However for large configurations with millions of binding table entries,
this can take a second or two, so it can still be useful to compile the
configuration ahead of time.

Use the `snabb lwaftr compile-configuration` command to compile a
configuration ahead of time.  If you do this, you can use the `snabb
lwaftr control PID reload` command to tell the Snabb process with the
given *PID* to reload the table.

## In-depth configuration explanation

See the embedded descriptions in the
[snabb-softwire-v1](../../../lib/yang/snabb-softwire-v1.yang) schema
file.

## Binding tables

A binding table is a collection of softwires (tunnels).  One endpoint
of the softwire is in the AFTR and the other is in the B4.  A
softwire provisions an IPv4 address (or a part of an IPv4 address) to
a customer behind a B4.  The B4 arranges for all IPv4 traffic to be
encapsulated in IPv6 and sent to the AFTR; the AFTR does the reverse.
The binding table is how the AFTR knows which B4 is associated with
an incoming packet.

In the Snabb lwAFTR there are three parts of a binding table: the PSID
info map, the border router (BR) address table, and the softwire map.

### PSID info map

The PSID info map defines the set of IPv4 addresses that are provisioned
by an lwAFTR.  It also defines the way in which those addresses are
shared, by specifying the "psid-length" and "shift" parameters for each
address.  See RFC 7597 for more details on the PSID scheme for how to
share IPv4 addresses.  IPv4 addresses are added to the `psid-map` with
statements like this:

``
  psid-map {
    addr 192.168.127.12;
    end-addr 192.168.127.12;
    psid-length 6;
    reserved-ports-bit-count 0;
    shift 10;
  }
``

`end-addr`, `reserved-ports-bit-count`, and `shift` are all optional.  

An entry's `psid-length`, `shift` and `reserved-ports-bit-count`
parameters must necessarily add up to 16, so it is sufficient to specify
just two of them.  Actually it's sufficient to just specify the
`psid-length`, which is the only required one.
`reserved-ports-bit-count` defaults to 0, and `shift` defaults to `16 -
psid-length`.

### Border router addresses

Next, the `br-address` clauses define the set of IPv6 addresses to
associate with the lwAFTR.  These are the "border router" addresses.
For a usual deployment there will be one main address and possibly some
additional ones.  For example:

```
  br-address 8:9:a:b:c:d:e:f;
  br-address 1E:1:1:1:1:1:1:af;
  ...
```

### Softwires<commit_msg>Syntax fix for README.configuration.md<commit_after># Configuration

The lwAFTR's configuration is modelled by a
[YANG](https://tools.ietf.org/html/rfc6020) schema,
[snabb-softwire-v1](../../../lib/yang/snabb-softwire-v1.yang).

The lwAFTR takes its configuration from the user in the form of a text
file.  That file's grammar is derived from the YANG schema; see the
[Snabb YANG README](../../../lib/yang/README.md) for full details.
Here's an example:

```
// IPv4 interface.
external-interface {
  allow-incoming-icmp true;
  // Limit ICMP error transmit rate to PACKETS/PERIOD.
  error-rate-limiting {
    packets 600000;
    period 2;
  }
  // Generate ICMP errors at all?
  generate-icmp-errors true;
  // Basic parameters.
  ip 10.10.10.10;
  mac 12:12:12:12:12:12;
  mtu 1460;
  // vlan-tag 42;
  // Where to go next.  Either one will suffice; if you specify the IP,
  // the next-hop MAC will be determined by ARP.
  next-hop {
    mac 68:68:68:68:68:68;
    ip 1.2.3.4;
  }
  // Control the size of the fragment reassembly buffer.
  reassembly {
    max-fragments-per-packet 40;
    max-packets 20000;
  }
}
// The same thing as for the external interface, but on the IPv6 side
// and with IPv6 addresses.
internal-interface {
  allow-incoming-icmp true;
  error-rate-limiting {
    packets 600000;
    period 2;
  }
  generate-icmp-errors true;
  // One more interesting thing -- here we control whether to support
  // routing traffic between two B4s.
  hairpinning true;
  ip fc00:e968:6179::de52:7100;
  mac 22:22:22:22:22:22;
  mtu 1500;
  // vlan-tag 64;
  next-hop {
    mac 44:44:44:44:44:44;
    // NDP instead of ARP of course.
    ip fc00:e968:6179::de52:7100;
  }
  reassembly {
    max-fragments-per-packet 40;
    max-packets 20000;
  }
}
// Now the binding table!  3 parts: PSID map, BR address table, and
// softwire set.  See description below for details.
binding-table {
  psid-map { addr 172.16.17.32; psid-length 4; }
  psid-map { addr 172.16.31.10; psid-length 16; }
  psid-map { addr 192.168.3.11; psid-length 16; }
  br-address fc00:e968:6179::de52:7100;
  br-address fc00:db20:35b:7399::5;
  br-address fd00:c2b6:b24b:be67:2827:688d:e6a1:6a3b;
  softwire {
    ipv4 172.16.31.10;
    psid 22788;
    b4-ipv6 fc00:db20:35b:7399::5;
  }
  softwire {
    ipv4 172.16.31.10;
    psid 2700;
    b4-ipv6 fc00:db20:35b:7399::5;
  }
  softwire {
    ipv4 172.16.17.32;
    psid 1;
    b4-ipv6 fc00:e968:6179::de52:7100;
  }
  softwire {
    ipv4 192.168.3.11;
    psid 7850;
    b4-ipv6 fc00:e968:6179::de52:7100;
    br 1;
  }
}
```

Basically there's an `external-interface` section defining the
parameters around the IPv4 interface that communicates with the
internet, an `internal-interface` section doing the same for the IPv6
side that communicates with the B4s, and then the `binding-table` that
declares the set of softwires.

## Compiling conigurations

When a lwAFTR is started, it will automatically compile its
configuration if it does not find a compiled configuration that's fresh.
However for large configurations with millions of binding table entries,
this can take a second or two, so it can still be useful to compile the
configuration ahead of time.

Use the `snabb lwaftr compile-configuration` command to compile a
configuration ahead of time.  If you do this, you can use the `snabb
lwaftr control PID reload` command to tell the Snabb process with the
given *PID* to reload the table.

## In-depth configuration explanation

See the embedded descriptions in the
[snabb-softwire-v1](../../../lib/yang/snabb-softwire-v1.yang) schema
file.

## Binding tables

A binding table is a collection of softwires (tunnels).  One endpoint
of the softwire is in the AFTR and the other is in the B4.  A
softwire provisions an IPv4 address (or a part of an IPv4 address) to
a customer behind a B4.  The B4 arranges for all IPv4 traffic to be
encapsulated in IPv6 and sent to the AFTR; the AFTR does the reverse.
The binding table is how the AFTR knows which B4 is associated with
an incoming packet.

In the Snabb lwAFTR there are three parts of a binding table: the PSID
info map, the border router (BR) address table, and the softwire map.

### PSID info map

The PSID info map defines the set of IPv4 addresses that are provisioned
by an lwAFTR.  It also defines the way in which those addresses are
shared, by specifying the "psid-length" and "shift" parameters for each
address.  See RFC 7597 for more details on the PSID scheme for how to
share IPv4 addresses.  IPv4 addresses are added to the `psid-map` with
statements like this:

```
  psid-map {
    addr 192.168.127.12;
    end-addr 192.168.127.12;
    psid-length 6;
    reserved-ports-bit-count 0;
    shift 10;
  }
```

`end-addr`, `reserved-ports-bit-count`, and `shift` are all optional.  

An entry's `psid-length`, `shift` and `reserved-ports-bit-count`
parameters must necessarily add up to 16, so it is sufficient to specify
just two of them.  Actually it's sufficient to just specify the
`psid-length`, which is the only required one.
`reserved-ports-bit-count` defaults to 0, and `shift` defaults to `16 -
psid-length`.

### Border router addresses

Next, the `br-address` clauses define the set of IPv6 addresses to
associate with the lwAFTR.  These are the "border router" addresses.
For a usual deployment there will be one main address and possibly some
additional ones.  For example:

```
  br-address fc00:e968:6179::de52:7100;
  br-address 1E:1:1:1:1:1:1:af;
  ...
```

### Softwires
{'fraction_non_alphanumeric': 0.0986366547717083, 'fraction_numerical': 0.06981425565010523, 'mean_word_length': 3.358054226475279, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 22, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5208836', 'n_tokens_mistral': 4291, 'n_tokens_neox': 3772, 'n_words': 1390}