<commit_before># Policy configuration

This page explains GoBGP policy feature for controlling the route
advertisement. It might be called Route Map in other BGP
implementations.

We explain the overview firstly, then the details, 

## Prerequisites

Assumed that you finished [Getting Started](https://github.com/osrg/gobgp/blob/master/docs/sources/getting-started.md).

## Contents
- [Overview](#overview)
- [Policy Model](#model)
- [Route Server Policy Model](#rs-model)
- [Policy Structure](#policy)
- [Policy Configuration](#configuration)
    - [Defining defined-sets](#defined-sets)
    - [Defining bgp-defined-sets](#bgp-defined-sets)
    - [Defining policy-definitions](#policy-definition)
    - [Attaching policy](#attachment)
        - [Attach policy to global rib](#global-attachment)
        - [Attach policy to route-server-client](#rs-attachment)

## <a name="overview"> Overview

Policy is a way to control how BGP routes inserted to RIB or advertised to
peers. Policy has two parts, **Condition** and **Action**. 
When a policy is configured, **Action** is applied to routes which meet **Condition**
before routes proceed to next step.

GoBGP supports **Condition** like `prefix`, `neighbor`(source/destination of the route),
`aspath` etc.., and **Action** like `accept`, `reject`, `MED/aspath/community manipulation`
etc...

You can configure policy by configuration file, CLI or gRPC API.
Here, we show how to configure policy via configuration file.

## <a name="model"> Policy Model

The following figure shows how policy works in normal BGP configuration.

<p align="center">
    <img src="./policy.png" alt="policy model"/>
</p>

There are **Import** and **Export** policy. **Import** policy is invoked
before best path calculation and pushing routes to RIB.
**Export** policy is invoked after that.

You can check each policy by the following commands.

```shell
$ gobgp global policy import
$ gobgp global policy export
```

## <a name="rs-model"> Route Server Policy Model

The following figure shows how policy works in [route server BGP configuration](https://github.com/osrg/gobgp/blob/master/docs/sources/route-server.md).

<p align="center">
    <img src="./rs-policy.png" alt="Announcement processing model implemented by the route server"/>
</p>

In route server mode, adding to **Import** and **Export**, we have **In** policy.

**Import** and **Export** policies are defined with respect to the
local routing table. The **Import** policy defines what routes will be
imported into its local RIBs. The **Export** policy defines what
routes will be exported from its local RIBs. **In** polices are
defined with respect to a peer. The **In** policy defines what routes will go
to other peers' local routing tables.

You can check each policy by the following commands.

```shell
$ gobgp neighbor <neighbor-addr> policy in
$ gobgp neighbor <neighbor-addr> policy import
$ gobgp neighbor <neighbor-addr> policy export
```

## <a name="policy"> Policy Stracture

<p align="center">
    <img src="./policy-component.png" alt="policy component"/>
</p>

A policy consists of statements. Each statement has condition(s) and action(s).

Conditions are categorized into attributes below:

- prefix
- neighbor
- aspath
- aspath length
- community
- extended community
- rpki validation result
- route type (internal/external/local)
- large community

As showed in the figure above, some of the conditions point to defined sets,
which are a container for each condition item (e.g. prefixes).

Actions are categorized into attributes below:

- accept or reject
- add/replace/remove community or remove all communities
- add/subtract or replace MED value
- set next-hop
- set local-pref
- prepend AS number in the AS_PATH attribute

When **ALL** conditions in the statement are `true`, the action(s) in the statement are executed.

You can check policy configuration by the following commands.

```shell
$ gobgp policy
$ gobgp policy statement
$ gobgp policy prefix
$ gobgp policy neighbor
$ gobgp policy as-path
$ gobgp policy community
$ gobgp policy ext-community
$ gobgp policy large-community
```

## <a name="configuration"> Policy Configuration

Policy Configuration comes from two parts, [definition](#defined-sets) and [attachment](#attachment).
For definition, we have [defined-sets](#defined-sets) and [policy-definition](#policy-definition).
**defined-sets** defines condition item for some of the condition type.
**policy-definitions** defines policies based on actions and conditions.

- **defined-sets**
    A single **defined-sets** entry has prefix match that is named **prefix-sets** and neighbor match part that is named **neighbor-sets**. It also has **bgp-defined-sets**, a subset of **defined-sets** that defines conditions referring to BGP attributes such as aspath. This **defined-sets** has a name and it's used to refer to **defined-sets** items from outside.

- **policy-definitions**
    **policy-definitions** is a list of policy. A single element has **statements** part that combines conditions with an action.

Below are the steps for policy configuration

1. define defined-sets
  1. define prefix-sets
  1. define neighbor-sets
1.  define bgp-defined-sets
  1. define community-sets
  1. define ext-community-sets
  1. define as-path-setList
  1. define large-community-sets
1. define policy-definitions 
1. attach policies to global rib (or neighbor local rib when neighbor is [route-server-client](https://github.com/osrg/gobgp/blob/master/docs/sources/route-server.md)).


### <a name="defined-sets"> 1. Defining defined-sets
defined-sets has prefix information and neighbor information in prefix-sets and neighbor-sets section, and GoBGP uses these information to evaluate routes.
Defining defined-sets is needed at first.
prefix-sets and neighbor-sets section are prefix match part and neighbor match part.

- defined-sets example

 ```toml
# prefix match part
[[defined-sets.prefix-sets]]
  prefix-set-name = "ps1"
  [[defined-sets.prefix-sets.prefix-list]]
    ip-prefix = "10.33.0.0/16"
    masklength-range = "21..24"

# neighbor match part
[[defined-sets.neighbor-sets]]
  neighbor-set-name = "ns1"
  neighbor-info-list = ["10.0.255.1"]
 ```

  ----

 #### prefix-sets
 prefix-sets has prefix-set-list, and prefix-set-list has prefix-set-name and prefix-list as its element. prefix-set-list is used as a condition.

 **prefix-set-list** has 1 element and list of subelement.

 | Element          | Description                        | Example       | Optional   |
 |------------------|------------------------------------|---------------|------------|
 | prefix-set-name  | name of prefix-set                 | "ps1"         |            |
 | prefix-list      | list of prefix and range of length |               |            |

 **PrefixLlist** has 2 elements.

 | Element          | Description       | Example        | Optional   |
 |------------------|-------------------|----------------|------------|
 | ip-prefix        | prefix value      | "10.33.0.0/16" |            |
 | masklength-range | range of length   | "21..24"       | Yes        |


 ##### Examples
 - example 1
    - Match routes whose high order 2 octets of NLRI is 10.33 and its prefix length is between from 21 to 24
    - If you define a prefix-list that doesn't have MasklengthRange, it matches routes that have just 10.33.0.0/16 as NLRI.<commit_msg>doc: update policy<commit_after># Policy configuration

This page explains GoBGP policy feature for controlling the route
advertisement. It might be called Route Map in other BGP
implementations.

We explain the overview firstly, then the details, 

## Prerequisites

Assumed that you finished [Getting Started](https://github.com/osrg/gobgp/blob/master/docs/sources/getting-started.md).

## Contents
- [Overview](#overview)
- [Policy Model](#model)
- [Route Server Policy Model](#rs-model)
- [Policy Structure](#policy)
- [Policy Configuration](#configuration)
    - [Defining defined-sets](#defined-sets)
    - [Defining bgp-defined-sets](#bgp-defined-sets)
    - [Defining policy-definitions](#policy-definition)
    - [Attaching policy](#attachment)
        - [Attach policy to global rib](#global-attachment)
        - [Attach policy to route-server-client](#rs-attachment)

## <a name="overview"> Overview

Policy is a way to control how BGP routes inserted to RIB or advertised to
peers. Policy has two parts, **Condition** and **Action**. 
When a policy is configured, **Action** is applied to routes which meet **Condition**
before routes proceed to next step.

GoBGP supports **Condition** like `prefix`, `neighbor`(source/destination of the route),
`aspath` etc.., and **Action** like `accept`, `reject`, `MED/aspath/community manipulation`
etc...

You can configure policy by configuration file, CLI or gRPC API.
Here, we show how to configure policy via configuration file.

## <a name="model"> Policy Model

The following figure shows how policy works in normal BGP configuration.

<p align="center">
    <img src="./policy.png" alt="policy model"/>
</p>

There are **Import** and **Export** policy. **Import** policy is invoked
before best path calculation and pushing routes to RIB.
**Export** policy is invoked after that.

You can check each policy by the following commands.

```shell
$ gobgp global policy import
$ gobgp global policy export
```

## <a name="rs-model"> Route Server Policy Model

The following figure shows how policy works in [route server BGP configuration](https://github.com/osrg/gobgp/blob/master/docs/sources/route-server.md).

<p align="center">
    <img src="./rs-policy.png" alt="Announcement processing model implemented by the route server"/>
</p>

In route server mode, adding to **Import** and **Export**, we have **In** policy.

**Import** and **Export** policies are defined with respect to the
local routing table. The **Import** policy defines what routes will be
imported into its local RIBs. The **Export** policy defines what
routes will be exported from its local RIBs. **In** polices are
defined with respect to a peer. The **In** policy defines what routes will go
to other peers' local routing tables.

You can check each policy by the following commands.

```shell
$ gobgp neighbor <neighbor-addr> policy in
$ gobgp neighbor <neighbor-addr> policy import
$ gobgp neighbor <neighbor-addr> policy export
```

## <a name="policy"> Policy Stracture

<p align="center">
    <img src="./policy-component.png" alt="policy component"/>
</p>

A policy consists of statements. Each statement has condition(s) and action(s).

Conditions are categorized into attributes below:

- prefix
- neighbor
- aspath
- aspath length
- community
- extended community
- rpki validation result
- route type (internal/external/local)
- large community

As showed in the figure above, some of the conditions point to defined sets,
which are a container for each condition item (e.g. prefixes).

Actions are categorized into attributes below:

- accept or reject
- add/replace/remove community or remove all communities
- add/subtract or replace MED value
- set next-hop
- set local-pref
- prepend AS number in the AS_PATH attribute

When **ALL** conditions in the statement are `true`, the action(s) in the statement are executed.

You can check policy configuration by the following commands.

```shell
$ gobgp policy
$ gobgp policy statement
$ gobgp policy prefix
$ gobgp policy neighbor
$ gobgp policy as-path
$ gobgp policy community
$ gobgp policy ext-community
$ gobgp policy large-community
```

## <a name="configuration"> Policy Configuration

Policy Configuration comes from two parts, [definition](#defined-sets) and [attachment](#attachment).
For definition, we have [defined-sets](#defined-sets) and [policy-definition](#policy-definition).
**defined-sets** defines condition item for some of the condition type.
**policy-definitions** defines policies based on actions and conditions.

- **defined-sets**
    A single **defined-sets** entry has prefix match that is named **prefix-sets** and neighbor match part that is named **neighbor-sets**. It also has **bgp-defined-sets**, a subset of **defined-sets** that defines conditions referring to BGP attributes such as aspath. This **defined-sets** has a name and it's used to refer to **defined-sets** items from outside.

- **policy-definitions**
    **policy-definitions** is a list of policy. A single element has **statements** part that combines conditions with an action.

Below are the steps for policy configuration

1. define defined-sets
  1. define prefix-sets
  1. define neighbor-sets
1.  define bgp-defined-sets
  1. define community-sets
  1. define ext-community-sets
  1. define as-path-setList
  1. define large-community-sets
1. define policy-definitions 
1. attach policies to global rib (or neighbor local rib when neighbor is [route-server-client](https://github.com/osrg/gobgp/blob/master/docs/sources/route-server.md)).


### <a name="defined-sets"> 1. Defining defined-sets
defined-sets has prefix information and neighbor information in prefix-sets and neighbor-sets section, and GoBGP uses these information to evaluate routes.
Defining defined-sets is needed at first.
prefix-sets and neighbor-sets section are prefix match part and neighbor match part.

- defined-sets example

 ```toml
# prefix match part
[[defined-sets.prefix-sets]]
  prefix-set-name = "ps1"
  [[defined-sets.prefix-sets.prefix-list]]
    ip-prefix = "10.33.0.0/16"
    masklength-range = "21..24"

# neighbor match part
[[defined-sets.neighbor-sets]]
  neighbor-set-name = "ns1"
  neighbor-info-list = ["10.0.255.1"]
 ```

  ----

 #### prefix-sets
 prefix-sets has prefix-set-list, and prefix-set-list has prefix-set-name and prefix-list as its element. prefix-set-list is used as a condition. Note that prefix-sets has either v4 or v6 addresses.

 **prefix-set-list** has 1 element and list of subelement.

 | Element          | Description                        | Example       | Optional   |
 |------------------|------------------------------------|---------------|------------|
 | prefix-set-name  | name of prefix-set                 | "ps1"         |            |
 | prefix-list      | list of prefix and range of length |               |            |

 **PrefixLlist** has 2 elements.

 | Element          | Description       | Example        | Optional   |
 |------------------|-------------------|----------------|------------|
 | ip-prefix        | prefix value      | "10.33.0.0/16" |            |
 | masklength-range | range of length   | "21..24"       | Yes        |


 ##### Examples
 - example 1
    - Match routes whose high order 2 octets of NLRI is 10.33 and its prefix length is between from 21 to 24
    - If you define a prefix-list that doesn't have MasklengthRange, it matches routes that have just 10.33.0.0/16 as NLRI.
{'fraction_non_alphanumeric': 0.1266684643386814, 'fraction_numerical': 0.008898476472967508, 'mean_word_length': 3.3994661921708187, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, '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': '732785', 'n_tokens_mistral': 4139, 'n_tokens_neox': 3980, 'n_words': 1656}