Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(agw): update network probe documentation #12403

Merged
merged 6 commits into from
Apr 22, 2022
Merged

docs(agw): update network probe documentation #12403

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
948b1c2
docs(agw): update network probe documentation
ymasmoudi Apr 5, 2022
36dc31c
docs(agw): update docusaurus
ymasmoudi Apr 5, 2022
7463efd
docs(agw): add small fixes
ymasmoudi Apr 5, 2022
3b674e1
fix review comments
ymasmoudi Apr 6, 2022
d4ae8a5
docs(agw): remove mention to nprobe-proxy
ymasmoudi Apr 15, 2022
b0856bf
remove extra space
ymasmoudi Apr 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/docusaurus/sidebars.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@
"howtos/he_api",
"howtos/inbound_roaming",
"howtos/pcap",
"howtos/l3_transport"
"howtos/l3_transport",
"howtos/network_probe"
]
},
{
Expand Down
97 changes: 50 additions & 47 deletions docs/readmes/howtos/network_probe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ title: Network Probe
hide_title: true
---

# Network Probe
# Lawfull Interception

## Overview

Network Probe allows a Magma operator to provide standardized lawful interception X2 and X3 interfaces as described in ETSI TS 103 221-2. This feature takes advantage of the rest API (swagger) to provide the X1 interface.
The Network Probe solution allows a Magma operator to provide standardized lawful interception X2 and X3 interfaces as described in [ETSI TS 103 221-2](https://www.etsi.org/deliver/etsi_ts/103200_103299/10322102/01.04.01_60/ts_10322102v010401p.pdf). This feature takes advantage of the rest API (swagger) to provide the X1 interface.

## Architecture

Expand All @@ -22,35 +22,46 @@ The LI feature can be summarized as follow,

### X1 Interface

It relies on the Orc8r Swagger API to configure intercept tasks and destinations. This interface uses Json content and thus is not 3GPP complaint. An external solution (nprobe-proxy) can handle the translation 3GPP (XML based) <-> Orc8r Swagger When required.
The X1 interface relies on the Orc8r Swagger API to configure intercept tasks and destinations. This interface uses Json content and thus is not 3GPP complaint. An external solution is needed to handle the translation between the 3GPP (XML based) and Orc8r Swagger when required.

Swagger nprobe endpoints allow the following,

#### 1. Tasks management

Network Probe Tasks represent an interception warrant and must be configured by LIMS. They provide the following information,

- TaskID : is UUID v4 representing an XiD identifier.
- TargetID : represents the subscriber identifier
- TargetType : represents the subscriber identifier type (IMSI, IMEI, MSISDN)
- DeliveryType : (events_only/all) states whether to deliver X2 or both X2 and X3 to the LIMS.
- Duration: specifies the lifetime of the task. If set to 0, the task will not expire until deleted through APIs.
- CorrelationID : allows to correlates X2 and X3 records. If not provided, Orc8r will generate a random value.
- task_id : is UUID v4 representing an XiD identifier.
- target_id : represents the subscriber identifier
- target_type : represents the subscriber identifier type (IMSI, IMEI, MSISDN). Only IMSI is supported now.
- delivery_type : (events_only/all) states whether to deliver X2 or both X2 and X3 to the LIMS.
- correlation_id : allows X2 and X3 records correlation. A random value is generated if not provided.
- operator_id : operator identifier
- domain_id : domain identifier
- duration : specifies the lifetime of the task. If set to 0, the task will not expire until deleted through APIs.
Comment on lines +33 to +40
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the names of those configurations was changed shortly, could we link the respective PR in the description of this pull request please.

Copy link
Collaborator Author

@ymasmoudi ymasmoudi Apr 6, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

previous names reflected internal go structures attributes.
this change correct that to use api endpoint json fields.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, could you still link the place / file, where they are defined in the code, please.


Each configured task in swagger will be then propagated to the appropriate service (nprobe, liagentd, pipelined)
Each configured task in swagger will be propagated to the appropriate services (nprobe, liagentd, pipelined).

#### 2. Destinations management

Network Probe Destinations represent the configuration of the remote server in charge of collecting the records.

- DeliveryAddress : provides the address of the remote server.
- DeliveryType : (events_only/all) states whether the server can receive X2 or both X2 and X3.
- delivery_address : provides the address of the remote server.
- delivery_type : (events_only/all) states whether the server can receive X2 or both X2 and X3.
- private_key : TLS private key to connect the delivery address
- certificate : TLS certificate to connect to the delivery address
- skip_verify_server : skip client verification when self-signed certificates are provided.

*Note that destination configuration is not currently taken in account. Only manual config is supported.*
*Note: The orc8r nprobe service (X2 Interface) processes the first destination only. Subsequent destinations are ignored.*

### X2 Interface

It is provided by the nprobe service in Orc8r. This service collects all the relevant events for targeted subscriber through elastic search from fluentd. Then, it parses them to create X2 records (aka Intercept Related Information - IRI) as specified ETSI TS 103 221-2 before exporting them to a remote server over TLS.
The X2 interface is provided by the nprobe service in Orc8r. This service collects all the relevant events for targeted subscriber from fluentd through elastic search. Then, it parses them to create X2 records (aka Intercept Related Information - IRI) as specified ETSI TS 103 221-2 before exporting them to a remote server over TLS.
The current list of supported records are:

- BearerActivation
- BearerModification
- BearerDeactivation
- EutranAttach.

### X3 Interface

Expand All @@ -71,12 +82,9 @@ Before starting to configure the LI feature, first you need to prepare the follo
- A remote TLS server to collect records and corresponding certificates.
- TLS Client certificates for X2 and X3 Interfaces

*Note that nprobe-proxy is provided outside magma project and will be described separately.*

## NetworkProbe Configuration

The following instructions use Orc8r Swagger API to configure Network Probe feature.
We will mainly use GET and POST methods to read and write from Swagger.
The following instructions use Orc8r Swagger API to configure Network Probe feature. We will mainly use GET and POST methods to read and write from Swagger.
Below are the steps to enable this feature in your current setup:

### 1. Enable LI mirroring in PipelineD in AGW
Expand All @@ -85,48 +93,26 @@ Edit /etc/magma/pipelined.yml

- Enable li_mirror in static_services list
- Set the following items,
- li_local_iface: eth2
- li_local_iface: gtp_br0
- li_mirror_all: false
- li_dst_iface: li_port
- restart pipelined

### 2. Enable LiAgentD service in AGW

Edit /etc/magma/liagentd.yml
Copy `nprobe.{pem,key}` to `/var/opt/magma/certs/`, then edit `/etc/magma/liagentd.yml`

- Enable the service
- Copy nprobe.pem/.key to /var/opt/magma/certs/
- Set the following remote TLS server information
- proxy_addr
- proxy_port
- cert_file
- key_file
- restart LiAgentD service

### 3. Configure the NProbe service in Orc8r

Similarly to the liagentd, you will need to configure orc8r with the appropriate details of
the remote server. This can be achieved automatically through terraform as follow,
*Note this service does not rely on Network Probe Destinations and must be configured manually.*

- Go to your terraform deployment directory
- Copy client certificates to your certs directory
- Load nprobe.pem/.key in secrets manager using

```bash
terraform taint module.orc8r-app.null_resource.orc8r_seed_secrets
terraform apply -target=module.orc8r-app.null_resource.orc8r_seed_secrets
```

- Set the following variables in your main.tf
- nprobe_operator_id
- nprobe_delivery_server
- nprobe_skip_verify_server

Then, run

```bash
terraform apply
```

### 4. Configure a NetworkProbe Task
### 3. Configure a NetworkProbe Task and Destination

Go to **Swagger API**:

Expand All @@ -140,6 +126,7 @@ Go to **Swagger API**:
"delivery_type": "events_only",
"domain_id": "string",
"duration": 300,
"operator_id": 1,
"target_id": "string",
"target_type": "imsi",
"timestamp": "2020-03-11T00:36:59.65Z"
Expand All @@ -150,9 +137,25 @@ Go to **Swagger API**:

*Note that timestamp, correlation ID, domain ID and duration are optional and can be skipped. Task ID must be a valid uuid v4.*

- Similarly, go to `nprobe` POST method `Add a new NetworkProbeDestination to the network` and set the content.
- Run the GET method again to see the applied changes.

```json
{
"destination_details": {
"delivery_address": "127.0.0.1:4040",
"delivery_type": "events_only",
"private_key": "string",
"certificate": "string",
"skip_verify_server": false
},
"destination_id": "29f28e1c-f230-486a-a860-f5a784ab9177"
}
```

## Test and Troubleshooting

It is recommendable that before running the tests, you enable some extra logging capabilities in both Access Gateway.
It is recommendable that before running the tests, you enable some extra logging capabilities in both Access Gateway and Orc8r.

For better details in Access Gateway logs:

Expand Down