Configure GenieACS

GenieACS General Config

config.json acts as the main configuration file and is stored in /path_to_genieacs/config/. In this folder there's also a backup file of the main(/default) config (config-sample.json). The following example shows some added options.

{
  "DATABASE_NAME" : "genieacs",
  "MONGODB_SOCKET" : "/tmp/mongodb-27017.sock",
  "REDIS_SOCKET" : "6379",
  "CWMP_INTERFACE" : "0.0.0.0",
  "CWMP_PORT" : 7547,
  "CWMP_SSL" : false,
  "NBI_INTERFACE" : "0.0.0.0",
  "NBI_PORT" : 7557,
  "FS_INTERFACE" : "0.0.0.0",
  "FS_PORT" : 7567,
  "FS_IP" : "192.168.0.1",
  "LOG_INFORMS" : true,
  "IGNORE_XML_NAMESPACES" : true,
  "LIBXMLJS_OPTIONS" : {"recover" : true},
  "DEBUG" : true
}

See the table for a more detailled description:

Parameter	Description
DATABASE_NAME	Defines the database name under which all data is stored in MongoDB
MONGODB_SOCKET	Defines the MongoDB socket file path and name
REDIS_SOCKET	Accept connections on the specified socket, default is 6379
CWMP_INTERFACE	Binds genieacs-cwmp to specified interface. If 0.0.0.0 is chosen, it listens to all available interfaces
CWMP_PORT	HTTP connections to ACS are accepted on the specified socket, default is 7547
CWMP_SSL	If set to true, switches ACS to HTTPS mode. A valid certificate is mandatory.
NBI_INTERFACE	Binds genieacs-nbi to specified interface. If 0.0.0.0 is chosen, it listens to all available interfaces
NBI_PORT	API connections accepted on the specified socket, default is 7557
NBI_SSL	If set to true, switches the NBI to HTTPS mode. A valid certificate is mandatory.
FS_INTERFACE	Binds genieacs-fs to specified interface. If 0.0.0.0 is chosen, it listens to all available interfaces
FS_PORT	File transfer connections are accepted on the specified socket, default is 7567
FS_IP	Specifies the IP address of the file-server, is used when sending download requests to a device
LOG_INFORMS	Specifies if INFORM are to be logged
DEBUG	Boolean. Logs the request/response from the CWMP process to/from the CPE. Resulting .dump files can be found ingenieacs/debug folder. To activate a dump for individual devices, use the format DEBUG-<device ID>. As an example "DEBUG-00AA11-VDSLCPE-123456789" : true
IGNORE_XML_NAMESPACES	If set to true, it allows XML traversal using element local names only. This might be needed, when the genieacs-cwmp worker dies on communication from cpe to acs
LIBXMLJS_OPTIONS	If set to true, it allows parsing XML even when the charset isn't UTF8 and values contain characters like �a^X*V�^R�^]�. This might be needed, when the genieacs-cwmp worker shows an error like this Error: PCDATA invalid Char value 29
GPN_NEXT_LEVEL	This will make the ACS fetch parameters in multiple requests which would make the CPE respond sooner for each request. Set this value to 2 if you have timeout issues with the CPE.
GPV_BATCH_SIZE	Defaults to 32. Set to a lower value if you encounter session timeouts with CPEs.
SESSION_TIMEOUT	Value in seconds. Defaults to 30. Increase this value as a last resort if you have timeout issues with your CPE. Try setting the GET_PARAMETER_NAMES_DEPTH_THRESHOLD value to 2 first, then 3 if you have to.

Beside the aforementioned configuration parameters, the following are implemented as well. All of them are stored in /pathtogenieacs/lib/config.coffee and define default values if the config options are not available in config.json. Keep in mind that all those are for internal use and shouldn't be change or inserted into config.json!:

Parameter	Description
CACHE_DURATION	in seconds
PRESETS_CACHE_DURATION	in seconds
PRESETS_TIME_PADDING
WORKER_RESPAWN_TIME
DEVICE_ONLINE_THRESHOLD
RETRY_DELAY	Defines retry time delay between a non-successful operation (task) and the following try, default is 300 seconds

GenieACS Auth Config

auth.js acts as the authentication configuration file and is stored in /path_to_genieacs/config/. In this folder there's also a backup file of the main(/default) config (auth-sample.js).

Authentication can be achieved on both directions, from CPE to ACS and, vice versa, from ACS to CPE. Within the InternetGatewayDevice.ManagementServer. Object, there are 2 pairs of authentication parameters defined.

CPE to ACS

InternetGatewayDevice.ManagementServer.Username
InternetGatewayDevice.ManagementServer.Password

Currently authentication to the ACS side (from CPE) is not implemented, yet. GenieACS will accept any incomming connection via HTTP/HTTPS and respond to it. This is a feature which will be implemented in the (near) future though. A workaround is to use nginx for auth from cpe to the acs side.

CPE to ACS with nginx and ssl

For this workaround it is only possible to make a auth with username/password the deviceid will not be checked! The genieacs services will be bind to the local interface "127.0.0.1". To use https for File Ddownload "FS_SSL" must be set to true to send the download request to the cpe with an https url enabled.

Edit genieacs/config/config.json

{
  "MONGODB_CONNECTION_URL" : "mongodb://127.0.0.1/genieacs",
  "REDIS_PORT" : "6379",
  "REDIS_HOST" : "127.0.0.1",
  "CWMP_INTERFACE" : "127.0.0.1",
  "CWMP_PORT" : 7547,
  "NBI_INTERFACE" : "127.0.0.1",
  "NBI_PORT" : 7557,
  "FS_INTERFACE" : "127.0.0.1",
  "FS_PORT" : 7567,
  "FS_HOSTNAME" : "tr069.tdt.de",
  "FS_SSL" : true,
  "LOG_INFORMS" : true,
  "DEBUG" : false
}

Bind genieacs-gui to inteface and port

./genieacs-gui-trunk/bin/rails s -p 8080 -b 127.0.0.1

On the same server we have to install nginx (Debian)

• sudo apt-get install nginx <- install nginx
• touch /etc/nginx/sites-available/tr069.tdt.de <- add new nginx config
• ln -s /etc/nginx/sites-available/tr069.tdt.de /etc/nginx/sites-enabled/tr069.tdt.de <- enable config

Redirect all http gui requests to https gui

server {
	listen         80;
	server_name    example.de;
	return         301 https://$server_name$request_uri;
}

Redirect all gui requests to local gui service

server {
	listen 10.1.4.17:443;
	server_name example.de;
	ssl on;
	ssl_certificate_key /home/tr069/genieacs/genieacs-trunk/config/acs_key.pem;
	ssl_certificate /home/tr069/genieacs/genieacs-trunk/config/acs_cert.pem;

	access_log /var/log/nginx/example.de.cwmp.gui.log combined;
	error_log /var/log/nginx/example.cwmp.gui.log;

	client_max_body_size 50M;

	location / {
		proxy_pass http://127.0.0.1:8080;
		#proxy_http_version 1.1;
		#proxy_set_header Upgrade $http_upgrade;
		#proxy_set_header Connection 'upgrade';
		#proxy_set_header Host $host;
		#proxy_cache_bypass $http_upgrade;
	}
}

Redirect all nbi requests to local nbi service

server {
	listen 10.1.4.17:7557;
	server_name example.de;
	ssl on;
	ssl_certificate_key /home/tr069/genieacs/genieacs-trunk/config/acs_key.pem;
	ssl_certificate /home/tr069/genieacs/genieacs-trunk/config/acs_cert.pem;

	access_log /var/log/nginx/example.de.nbi.log combined;
	error_log /var/log/nginx/example.de.nbi.log;

	location / {
		proxy_pass http://127.0.0.1:7557;
		#proxy_http_version 1.1;
		#proxy_set_header Upgrade $http_upgrade;
		#proxy_set_header Connection 'upgrade';
		#proxy_set_header Host $host;
		#proxy_cache_bypass $http_upgrade;
		proxy_set_header Authorization "";
		auth_basic "Restricted";
		auth_basic_user_file /etc/nginx/ms-htpasswd;
	}
}

Redirect all cwmp requests to local cwmp service

server {
	listen 10.1.4.17:7547;
	server_name example.de;
	ssl on;
	ssl_certificate_key /home/tr069/genieacs/genieacs-trunk/config/acs_key.pem;
	ssl_certificate /home/tr069/genieacs/genieacs-trunk/config/acs_cert.pem;

access_log /var/log/nginx/example.de.cwmp.log combined;
error_log /var/log/nginx/example.de.cwmp.log;

location / {
	proxy_pass http://127.0.0.1:7547;
	#proxy_http_version 1.1;
	#proxy_set_header Upgrade $http_upgrade;
	#proxy_set_header Connection 'upgrade';
	#proxy_set_header Host $host;
	#proxy_cache_bypass $http_upgrade;
	proxy_set_header Authorization "";
	auth_basic "Restricted";
	auth_basic_user_file /etc/nginx/ms-htpasswd;
}

}

Redirect all fs requests to local fs service

server {
	listen 10.1.4.17:7567;
	server_name example.de;
	ssl on;
	ssl_certificate_key /home/tr069/genieacs/genieacs-trunk/config/acs_key.pem;
	ssl_certificate /home/tr069/genieacs/genieacs-trunk/config/acs_cert.pem;

	access_log /var/log/nginx/example.de.fs.log combined;
	error_log /var/log/nginx/example.de.fs.log;

	location / {
		proxy_pass https://127.0.0.1:7567;
		#proxy_http_version 1.1;
		#proxy_set_header Upgrade $http_upgrade;
		#proxy_set_header Connection 'upgrade';
		#proxy_set_header Host $host;
		#proxy_cache_bypass $http_upgrade;
		proxy_set_header Authorization "";
		auth_basic "Restricted";
		auth_basic_user_file /etc/nginx/ms-htpasswd;
	}
}

Create links for cert and key file:

cd genieacs-trunk/config/
ln -s acs_key.pem fs.key
ln -s acs_cert.pem fs.crt

Create /etc/nginx/ms-htpasswd with the format described here.

ACS to CPE

InternetGatewayDevice.ManagementServer.ConnectionRequestUsernameInternetGatewayDevice.ManagementServer.ConnectionRequestPassword

The configuration file auth.js is used for ACS to CPE connection request authentication. By default, the deviceId is used as the username.

function connectionRequest(deviceId, url, username, password, callback) {
  return callback(username || deviceId, password || "");
}

After defining a pair of credentials this file should look like:

"use strict";

function connectionRequest(deviceId, url, username, password, callback) {
  return callback('someUsername', 'somePassword');
}

exports.connectionRequest = connectionRequest;

In the default implementation, you can put just one pair of fixed credentials into it but it's a javascript file and you're free to implement any logic you need to provide the passwords.

After making changes to the config/auth.js file, it is necessary to restart the NBI.

GenieACS SSL

In it's default-state GenieACS is accessed via an unencrypted HTTP connection. If you establish the TR-069 connection via a public network (e.g. "Internet"), this leads to the problem that confidential information are exchange as plain text (for example confidential SIP credential).

To establish an encrypted connection via CPE and GenieACS (and vice versa), you need the following:

• a valid certificate (by a Certificate Authority or as self-signed certificate)
• a CPE capable of storing (additional) certificates

In the /pathtogenieacs/config/ folder are two example files, httpscert.crt (the certificate) and httpscert.key (the private key to the certificate). It's a self-signed certifcate by Zaid (owner of GenieACS). WARNING!: Don't use those both, because the certificate is allready expired!

To use this certificate you have to push it onto your CPE. Most CPEs allow to upload a certificate, which to trust, via it's web interface. If your CPE doesn't support this, it might be neccessary to implement it into the filesystem.

What if I don't have a certificate from a CA?:

If you didn't bought/got a certificate from a CA, you can self-sign one. For this you need openssl installed (use the latest version). To generate them, use the following commands:

openssl genrsa 1024 > key.pem
openssl req -new -x509 -key key.pem > cert.pem

Attention1:Without "-days " paramter the certificate is valid for one month. If you like to have a higher validity, you have to append -days 3650, e.g. 10 years, after -x509.

Attention2: When the second command is issued, there are multiple prompts to enter data for that certificate. The most important one is the CN (common name) field. Don't give a name here! If you do, you likely run into "domain mismatch" errors. Enter either the IP or the URL of the server, where GenieACS is hosted on.

User@Host:~$ openssl req -x509 -new -key key.pem > cert.pem
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Hamburg
Locality Name (eg, city) []:Hamburg
Organization Name (eg, company) [Internet Widgits Pty Ltd]:ACS
Organizational Unit Name (eg, section) []:ACSTest
Common Name (e.g. server FQDN or YOUR name) []:mydomain.toacs.com
Email Address []:help@toacs.com
User@Host:~$

After generating both files (key.pem/cert.pem) copy both into the config/ folder as key.key (key.pem) and cert.crt (cert.pem). For each GenieACS service you wish to run in secure mode, you will need to set the corresponding config entry _SSL entry to true, and copy/link the key.key and cert.crt to servicename.key/crt. For example, if you want to run the CWMP in SSL mode, set the CWMP_SSL entry to true in config/config.json, and copy/link cert.crt to cwmp.crt and key.key to cwmp.key.

The next step is to include this self-signed certificate onto the CPE. There is no general tutorial for that, because it depends on the provided options of the CPE. In this tutorial case it was possible to upload a certificate via CPE's web interface.

After that, change the ManagementURL of the CPE to a "HTTPS URL" and start GenieACS. When the TR-069 client of the CPE tries to connect, it should do it via an encrypted connection.

After GenieACS is configured correctly, the certificate is loaded into the CPE, and the ManagementURL is updated, you will need to restart GenieACS.

tr69c:243.822:verify_callback:202:error_num = 0, err_msg = ok, depth = 0,
subject = /C=DE/ST=Hamburg/L=Hamburg/O=ACS/OU=ACSTesting/CN=192.168.1.3/emailAddress=Chr.Heyl@googlemail.com,
issuer = /C=DE/ST=Hamburg/L=Hamburg/O=ACS/OU=ACSTesting/CN=192.168.1.3/emailAddress=Chr.Heyl@googlemail.com

tr69c:243.823:verify_callback:216:return X509_V_OK, CN = 192.168.1.3, URL = https://192.168.1.3:7548

tr69c:243.837:stopListener:172:removed listener on fd=5

refer:https://github.com/genieacs/genieacs/wiki/Configure-GenieACS