Home
Welcome to bromelia-eir wiki!
bromelia-eir is fun to use and absolutely easy to add new functionalities. It is the first official implementation of a Diameter-based protocol application by using the Python's Bromélia library. It is designed to run as Docker containers.
-
eir_app-app: the entrypoint which connects directly either to MME or to DRA over S13/S13' interface. Whenever an incoming S13/S13' Diameter request reaches this container, it processes and fire a query towards to central database. -
eir_app-postgres: the central database which holds all the denied & greylisted devices. It comes powered with a PostgreSQL database service under the hood. -
eir_app-pgadmin: the EIR's database administrative point powered with pgAdmin tool.
bromelia-eir implements the ETSI TS 129 272 V15.4.0 (2018-07) technical specification. However, if you need to customize it in any way just go and play around.
Please make sure that you have the latest version. You can download the source code from here or clone the repository:
$ git clone https://github.com/heimiricmr/bromelia-eir.gitHost system
- Linux based distro or MacOS (with support to Python 3.7 or later)
- Python 3.7 or later
- Docker 20.10.7 or later
- docker-compose 1.29.2 or later
Containers dependencies
- Python dependencies (pyyaml, psycopg2-binary, sqlalchemy & bromelia)
- PostgreSQL 11 or later
- pgAdmin 4 or later
NOTE: Bromelia-EIR was developed and tested on an Apple silicon. It is pretty likely work properly in Linux based distros in general.
Once Host system requirements are installed, just go to the project folder and issue the docker-compose command below.
$ cd bromelia-eir/eir_app
$ docker-compose up -d
Creating network "eir_app_network" with the default driver
Creating eir_app-postgres ... done
Creating eir_app-app ... done
Creating eir_app-pgadmin ... doneDone! You've just instantiated your open source EIR platform! See it.
$ docker container ls -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d0872226c878 dpage/pgadmin4 "/entrypoint.sh" About a minute ago Up About a minute 443/tcp, 0.0.0.0:15432->80/tcp, :::15432->80/tcp eir_app-pgadmin
6b17df08cd40 eir_app_app "./boot.sh" About a minute ago Up About a minute 0.0.0.0:3870->3870/tcp, :::3870->3870/tcp eir_app-app
8a85200a54be eir_app_postgres "docker-entrypoint.s…" About a minute ago Up About a minute 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp eir_app-postgresThe EIR platform is running waiting for an incoming CEX procedure. As per current configuration, you may use a dummy MME which generates S13/S13' ME-Identity-Check-Request just to validate the EIR will reply such requests. Surely, it will reply all requests with a WHITE_LISTED status because the database is way empty.
You may find the dummy MME at bromelia-eir/tests/s13_mme.py module. Run it with your preferred Python interpreter. Don't forget to install Bromelia library before.
The CEX procedure between your dummy MME and the EIR platform is the first thing to take place. Connection established - it will ask you to provide a few informations to fire requests towards to your brand new running open source EIR platform.
Below you see an example. Let's break it down.
$ python bromelia-eir/tests/s13_mme.py
* Running Diameter app (3GPP Gx) on 127.0.0.1:3868 as CLIENT mode (CEX)
* Diameter connection on 127.0.0.1:3868 is now up
===================================================
>> Total number of messages: 10
>> Number of messages per cycle: 2
>> Cycle extension (in seconds): 1
sent: 2, recvd: 0, pending: 2 (0.0%)
sent: 4, recvd: 2, pending: 2 (50.0%)
sent: 6, recvd: 4, pending: 2 (67.0%)
sent: 8, recvd: 6, pending: 2 (75.0%)
sent: 10, recvd: 8, pending: 2 (80.0%)
executed time: 5 seconds
tps: 2.0 msgs/seconds
===================================================
>> Continue with more performance testing? (Y/N) N
* Diameter connection on 127.0.0.1:3868 is now downThe total number of messages refers to the total number of ME-Identity-Check-Request messages you want to send to EIR platform. The Number of messages per cycle refers to how many ME-Identity-Check-Request messages you want to send at once. In other words, it is going to send as many messages as you want in a single TCP stream burst. The Cycle extension (in seconds), finally, refers to the time between burst.
After parameter values provided it will start to send message and show off how many requests have been sent, how many answers have been received/recvd and how many answer are pending to be received. The percentage on the rightside refers to number of messages received and sent ratio.
At the end, it is going to notify you with a pretty basic statistics regarding to total executed time and transactions per seconds, or tps.
If you want to keep playing around just type "Y" to proceed for more tests. However, keep in mind this tool has limitations and may not reach TPS high values. It means low values of Cycle extension (in seconds) combined with high values of Number of messages per cycle may lead to abnormal behavior.
Moreover if you want to change the IMEISV and IMSI's lower limit value found in the dummy ME-Identity-Check-Request messages, just update the imei and imsi variables found in the create_ecr() function and run the bromelia-eir/tests/s13_mme.py module again.
We have built so far a good understanding about Bromelia-EIR. However we did not integrate it to any real MME. If you want to do so, be a production be a staging one, you just need to update the eir_app/app/config.yaml file with your local and peer nodes defined.
Below you may find firstly the default config.yaml file followed by an example.
api_version: v1
name: EIR
spec:
- applications:
- vendor_id: VENDOR_ID_3GPP
app_id: DIAMETER_APPLICATION_S13_S13
mode: Server
watchdog_timeout: 30
local:
ip_address: 0.0.0.0
hostname: eir.epc.mynetwork.com
realm: epc.mynetwork.com
port: 3870
peer:
ip_address: 0.0.0.0
hostname: mme.epc.mynetwork.com
realm: epc.mynetwork.com
port: 3868api_version: v1
name: EIR
spec:
- applications:
- vendor_id: VENDOR_ID_3GPP
app_id: DIAMETER_APPLICATION_S13_S13
mode: Server
watchdog_timeout: 30
local:
ip_address: 0.0.0.0
hostname: eir00.epc.mnc000.mcc999.3gppnetwork.org
realm: epc.mnc000.mcc999.3gppnetwork.org
port: 3870
peer:
ip_address: 10.129.241.235
hostname: mme00.epc.mnc000.mcc999.3gppnetwork.org
realm: epc.mnc000.mcc999.3gppnetwork.org
port: 3871From the local node's perspective, you will change only the hostname and realm keys. Do not change the local IP address, because the container must be listening in localhost in order to receive TCP connections. From the peer node's perspective, you will change as per your requirements. It means that depending on the platform you are going to integrate (eg. MME, DRA), you must overwrite all the peer node's 4 keys.
That's pretty much everything you need to know to run it.
Setup a tcpdump tracing to see the ongoing traffic. Have fun!
