diff --git a/README.md b/README.md index 6276512c5..9b4b8f978 100644 --- a/README.md +++ b/README.md @@ -16,21 +16,11 @@ NextEPC contains the PCRF (Policy and Charging Rules Function), which controls t Installation ============ -This post will guide you on how to get installed **NextEPC** with your environment. To date, NextEPC has been tested on GNU/Linux distributions(Debian, Ubuntu, CentOS, Fedora), FreeBSD, and Mac OS X. - - - -## Ubuntu - -To get the latest Ubuntu version, please visit the official Ubuntu website: [https://www.ubuntu.com/download/](https://www.ubuntu.com/download/). - * ### MME, SGW, PGW, HSS, and PCRF The NextEPC package is available on the recent versions of Ubuntu. ```bash -sudo apt-get update -sudo apt-get -y install software-properties-common sudo add-apt-repository ppa:acetcom/nextepc sudo apt-get update sudo apt-get -y install nextepc @@ -60,10 +50,6 @@ sudo systemctl restart nextepc-mmed (Stop and start) * ### Web User Interface -The LTE user subcription information of NextEPC is stored and maintained by [Mongo DB](https://www.mongodb.com/). To manage the subscriber information, [Mongo DB client](https://docs.mongodb.com/ecosystem/tools/) is required, and this client can connect to the DB URI [_mongodb://localhost/nextepc_]. - -NextEPC provides an alternative management interface for customers to manage their subscriber information in an easy way, that is **Web User Interface**. The following shows how to install the Web UI of NextEPC. - ```bash sudo apt-get -y install curl curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - @@ -77,7 +63,6 @@ sudo systemctl start nextepc-webui ``` - * ### Uninstall NextEPC ```bash @@ -91,355 +76,17 @@ sudo rm -Rf /var/log/nextepc ``` -## CentOS, Fedora, FreeBSD, and Mac OS X +## Documentation -For these OS, you should build NextEPC from the code. First clone this [repository](https://github.com/acetcom/nextepc.git) and then follow instructions described in the [documentation](http://nextepc.org/docs/). +If you don't understand something about NextEPC, the [http://nextepc.org](http://nextepc.org/) is a great place to look for answers. -* ### [CentOS](http://nextepc.org/docs/build/1-centos) -* ### [Fedora](http://nextepc.org/docs/build/2-fedora) -* ### [FreeBSD](http://nextepc.org/docs/build/3-freebsd) -* ### [Mac OS X](http://nextepc.org/docs/build/4-macosx) -Build -===== +## Support -Since NextEPC is an open source project, you can build and use this program directly from source code. If you have already installed it with a package manager, or are not interested in learning the source code, you can skip this guide and proceed to the next [configuration guide](http://nextepc.org/guides/3-configuration). +Problem with NextEPC can be filed as [issues](https://github.com/acetcom/nextepc/issues) in this repository. And also, we've created slack workspace named _nextepc.slack.com_. Use [this link](https://join.slack.com/t/nextepc/shared_invite/enQtMzMyMTIwMzY2MTAyLTJjYzQyYWFhYWZmNTBmNmFmY2EzMzJlY2VhYWMzYzY1NTE1YWYzZjFiMDM4ZDIxNDRhZTRmY2M2YmI4NzdmZjI) to get started. -Note that this guide is based on Ubuntu 16.04.3(Zenial) Distribution. -## Prerequisites +## License -NextEPC requires MongoDB and TUN device. If you have previously installed NextEPC according to the [Installation Guide](http://nextepc.org/guides/1-installation), they was configured at that time. So, you can skip this step. +NextEPC source files are made avaiable under the terms of the GNU Affero General Public License (GNU AGPLv3). See [this link](http://nextepc.org/docs/nextepc/4-license/) -Install Mongo DB with Package Manager. -```bash -sudo apt-get -y install mongodb -sudo systemctl start mongodb (if '/usr/bin/mongod' is not running) -``` - -To run NextEPC with least privilege, TUN device permission should be a `crw-rw-rw-`(666). Otherwise, you need to run nextepc daemon with root privilege. If the permission is not `crw-rw-rw-`(666), you may need to install `udev` package. Nevertheless, if the permission do not change , you can run nextepc with root privileges or change the permission using `chmod 666 /dev/net/tun`. - -```bash -ls -al /dev/net/tun -crw-rw---- 1 root 28 10, 200 Feb 11 05:13 /dev/net/tun -sudo apt-get install udev -sudo systemctl start systemd-udevd (if '/lib/systemd/systemd-udevd' is not running) -``` - -Write the configuration file for the TUN deivce. -```bash -sudo sh -c "cat << EOF > /etc/systemd/network/99-nextepc.netdev -[NetDev] -Name=pgwtun -Kind=tun -EOF" -``` - -Craete the TUN device. Interface name will be `pgwtun`. -``` -sudo systemctl enable systemd-networkd -sudo systemctl restart systemd-networkd - -sudo apt-get -y install net-tools -ifconfig pgwtun -``` - -Then, you need to check *IPv6 Kernel Configuration*. Although you can skip this process, we recommend that you set this up to support IPv6-enabled UE. - -```bash -sysctl -n net.ipv6.conf.pgwtun.disable_ipv6 - -(if the output is 0 and IPv6 is enabled, skip the followings) -sudo sh -c "echo 'net.ipv6.conf.pgwtun.disable_ipv6=0' > /etc/sysctl.d/30-nextepc.conf" -sudo sysctl -p /etc/sysctl.d/30-nextepc.conf -``` - -You are now ready to set the IP address on TUN device. If IPv6 is disabled for TUN device, please remove `Address=cafe::1/64` from below. - -```bash -sudo sh -c "cat << EOF > /etc/systemd/network/99-nextepc.network -[Match] -Name=pgwtun -[Network] -Address=45.45.0.1/16 -Address=cafe::1/64 -EOF" -``` - -Check the TUN(pgwtun) device again. -``` -sudo systemctl restart systemd-networkd -ifconfig pgwtun -``` - - -## MME, SGW, PGW, HSS, and PCRF - -Install the depedencies for building the source -```bash -sudo apt-get -y install autoconf libtool gcc pkg-config git flex bison libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libmongoc-dev libbson-dev libyaml-dev -``` - -Git clone and compile -```bash -acetcom@nextepc:~$ git clone https://github.com/acetcom/nextepc -ccetcom@nextepc:~$ cd nextepc -acetcom@nextepc:~/nextepc$ autoreconf -iv -acetcom@nextepc:~/nextepc$ ./configure --prefix=`pwd`/install -acetcom@nextepc:~/nextepc$ make -j `nproc` -acetcom@nextepc:~/nextepc$ make install -``` - -We provide a program that checks whether the installation is correct. After running the wireshark, select `loopback` interface, filter `s1ap || diameter || gtpv2 || gtp` and run `./test/testepc`. You can see the virtually created packets. [[testepc.pcapng]](http://nextepc.org/static/pcapng/testepc.pcapng) - -Note that you should stop all nextepc daemons before running test program if you have already installed it with a package manage. -```bash -(if nextepc-daemons are running) -sudo systemctl stop nextepc-mmed -sudo systemctl stop nextepc-sgwd -sudo systemctl stop nextepc-pgwd -sudo systemctl stop nextepc-hssd -sudo systemctl stop nextepc-pcrfd - -acetcom@nextepc:~/nextepc$ ./test/testepc -``` - -It is a convenient tool called `nextepc-epcd` for developers. This daemon includes both *MME*, *SGW*, *PGW*, *HSS*, and *PCRF*. So, instead of running all 5 daemons, you can just run `nextepc-epcd` in your development environment. - -```bash -acetcom@nextepc:~/nextepc$ ./nextepc-epcd -NextEPC daemon v0.3.3 - Feb 11 2018 07:19:59 - - PID[3720] : '/home/acetcom/nextepc/install/var/run/nextepc-epcd/pid' - File Logging : '/home/acetcom/nextepc/install/var/log/nextepc/nextepc.log' - MongoDB URI : 'mongodb://localhost/nextepc' - Configuration : '/home/acetcom/nextepc/install/etc/nextepc/nextepc.conf' -[02/11 07:26:42.001] PCRF try to initialize -... -``` - -When you run `nextepc-epcd`, all logs for MME, SGW, PGW, PCRF, and HSS are written to `nextepc.log`, and all settings are managed in one place for `nextepc.conf`. You can find the log/conf path at the beginning of running screen. - -Sometimes, you may want to use newly updated source code. -```bash -(Control-C kill nextepc-epcd) -acetcom@nextepc:~/nextepc$ make maintainer-clean -acetcom@nextepc:~/nextepc$ rm -rf ./install -acetcom@nextepc:~/nextepc$ git pull -acetcom@nextepc:~/nextepc$ autoreconf -iv -acetcom@nextepc:~/nextepc$ ./configure --prefix=`pwd`/install -acetcom@nextepc:~/nextepc$ make -j `nproc` -acetcom@nextepc:~/nextepc$ make install -acetcom@nextepc:~/nextepc$ ./nextepc-epcd -``` - -## Web User Interface - -To get the latest [Node.js](https://nodejs.org/) and [NPM](https://www.npmjs.com/), please visit the official Node.js website: -[https://nodesjs.org/en/download/](https://nodesjs.org/en/download/). - -Or, you can install [Node.js](https://nodejs.org/) and [NPM](https://www.npmjs.com/) with a package manager. - -```bash -sudo apt-get -y install curl -curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - -sudo apt-get -y install nodejs -``` - -Install the dependencies to run WebUI - -```bash -acetcom@nextepc:~/nextepc$ cd webui -acetcom@nextepc:~/nextepc/webui$ npm install -``` - -Running WebUI - -```bash -acetcom@nextepc:~/nextepc/webui$ npm run dev -``` - -Now the web server is running on _http://localhost:3000_. - - -Configuraiton -============= - -In LTE, there are tons of configurable parameters. This page will guide you to set essential parameters up. The configuration consists of three parts: IP network connectivity, LTE network settings and Subscribers registering. - -## 1. IP Connectivity between Network Entities - -The minimum requirement of having IP connectvity is to modify the configuration files of MME and SGW. Once NextEPC has been installed, you can find [YAML](http://yaml.org/)-format configuration files in `/etc/nextepc/*.conf`. - -Note that [/etc/nextepc/nextepc.conf](https://github.com/acetcom/nextepc/blob/master/support/config/nextepc.conf.in) is just a manual. If you use `nextepc-epcd` in a build environment, this configuration file could be used, but if you installed it with the package manager, modifying this configuration file has no effect. - -Anyway, before setting up, please decide a network interface to run NextEPC, and then the IP address of the interface needs to be recorded in the configuration files. - -### Modification of MME config - -Open `/etc/nextepc/mme.conf` file, and find an item in mme → s1ap. Please set your IP address with putting `addr:` keyword. - -```yaml -mme: - freeDiameter: mme.conf - s1ap: - addr: -... -``` - -Save and exit. - -### Modification of SGW config - -Open `/etc/nextepc/sgw.conf` file, and find an item in sgw → gtpu. Please set your IP address with putting `addr:` keyword. - -```yaml -sgw: - gtpc: - addr: 127.0.0.2 - gtpu: - addr: -... -``` - -Save and exit. - - -### Adding a route for UE to have Internet connectivity - -By default, a LTE UE will receive a IP address with the network address of 45.45.0.0/16. If you have a [NAT](https://en.wikipedia.org/wiki/Network_address_translation) router (e.g., wireless router, cable modem, etc), the LTE UE can reach Internet in uplink, but it cannot in downlink. It's because the NAT router has no idea on 45.45.0.0/16, so adding a route is required. Please refer to the user manual to know how to add a static route in your router. - -Add a route of both 45.45.0.0/16 and cafe::0/64 to go the PGW IP address. For example, a command for Linux will be: - -```bash -sudo ip route add 45.45.0.0/16 via -sudo ip route add cafe::0/64 via -``` - -If you have no NAT router, there is another option for you. `iptables` can solve the problem. You execute the following command in NextEPC installed host. The `eth0` shown below is just an example. Do not miss out on modifying your interface name(e.g `enp0s25`, `wls3`). - -```bash -sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward" -sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE -sudo iptables -I INPUT -i pgwtun -j ACCEPT -``` - -## 2. LTE Network Settings - -### PLMN and TAC - -By default, LTE PLMN and TAC are set as shown in the following: - -```yaml -mme: - gummei: - plmn_id: - mcc: 001 - mnc: 01 - mme_gid: 2 - mme_code: 1 - tai: - plmn_id: - mcc: 001 - mnc: 01 - tac: 12345 -``` - -The LTE EnodeBs need to be set to use the same values of PLMN and TAC in NextEPC. If you want to change them, please modifiy in `/etc/nextepc/mme.conf`. - - -### Restarting MME and SGW. - -After changing conf files, please restart NextEPC daemons. - -```bash -sudo systemctl restart nextepc-mmed -sudo systemctl restart nextepc-sgwd -``` - -## 3. Register a subscriber - -Open _http://localhost:3000_. Login with **admin**. Later, you can change the password in _Account_ Menu. - -```markdown - - Username : admin - - Password : 1423 -``` - -Using Web UI, you can add a subscriber without a Mongo DB client. - -```markdown - - Go to Subscriber Menu. - - Click `+` Button to add a new subscriber. - - Fill the IMSI, security context(K, OPc, AMF), and APN of the subscriber. - - Click `SAVE` Button -``` - -This addition affects immediately NextEPC without restaring any daemon. - -## Appendix - -When you install NextEPC for the first time, the default configuration looks like this: - -### Network - -``` -* MME - S1AP: listen on all address avaiable in system - GTP-C: listen on the first IP address in system - DIAMETER: 127.0.0.2 (No TLS) - -* SGW - GTP-C: 127.0.0.2 - GTP-U: listen on the first IP address in system - -* PGW - GTP-C: Both 127.0.0.3 and [::1] - GTP-U: Both 127.0.0.3 and [::1] - DIAMETER: 127.0.0.3 (No TLS) - -* HSS - DIAMETER: 127.0.0.4 (No TLS) - -* PCRF - DIAMETER: 127.0.0.5 (No TLS) -``` - -### GUMMEI, PLMN and TAC - -``` -* GUMMEI - PLMN ID - MNC: 001, MCC: 01 - MME Group : 2 - MME Code : 1 - -* TAI - PLMN ID - MNC: 001, MCC: 01 - TAC : 12345 -``` - -### Security - -``` -* Integrity : EIA1 - Snow 3G -* Ciphering : EEA0 - Nothing -``` - -### UE Network - -``` -* IPv4 : 45.45.0.1/16 -* IPv6 : cafe::1/64 -``` - -### DNS - -``` -* IPv4 - Primary : 8.8.8.8 - Secondary : 8.8.4.4 - -* IPv6 - Primary : 2001:4860:4860::8888 - Secondary : 2001:4860:4860::8844 -```