<commit_before>#The TBAM Agent
The TBAM Agent is a daemon running on the OpenFlow Gateway (OFGW) and is responsible for the configuration Management Plane, Control Plane and Data Plane. OFGW is deployed as a Debian 6 Linux machine (real or virtual) and is configured/controlled by the TBAM Agent daemon. Regarding the Management plane, TBAM Agent permits not only to manage the configuration of the network devices, but also to retrieve the information of the forwarding plane thanks to pre-defined functionalities exposed by the Management plane. Moreover, the OFGW is in-charge of redirecting the Control traffic to the user controller and handling the data traffic from and to OFELIA islands. Consequently, TBAM Agent provides the configuration also of Control and Data Plane. The architecture of the OFGW is summarized in bottom port of [figure](https://wiki.man.poznan.pl/alien/img_auth.php/a/a4/Work_distribution.png).

##INSTALLATION
The communication with the [TBAM Resource Manager](https://github.com/fp7-alien/OCF-TBAM/blob/master/TBAM-RM/README.md#tbam-resource-manager) is obtained with a SecureXMLRPC interface. 
For testing purposes, the RPC server in the TBAM Agent and the TBAM RM use pre-installed certificates. In real deployments, the [ClearingHouse](http://www.eict.de/c-bas) can be used to generate the certificates. The TBAM Agent uses three certificates for the SecureXMLRPC authentication; moreover, the references contained in the code must be compliant with your local path. In particular, the parameters of the certificates used in the TBAM Agent are:

Parameter | Reference
------------- | -------------
SERVER_KEY_PATH | it refers to the server key.
SERVER_CERT_PATH |  it refers to the server cert. 
TRUSTED_CERT_PATH | it refers to trusted certificate issued by Clearinghouse.

On the other hand, in order to communicate with the TBAM Agent, the TBAM Resource Manager must use the correct client certificates defined by parameters *CLIENT_KEY_PATH* and *CLIENT_CERT_PATH* within the [Resource Manager's code](https://github.com/fp7-alien/OCF-TBAM)

The TBAM Agent can be started entering the folder OCF-OFGW/TBAM-Agent (e.g., *cd OCF-OFGW/TBAM-Agent*) and running the "src/main.py" with python (e.g., *python src/main.py*). The TBAM Agent has been tested with Python version 2.7.

To connect the Resource Manager to the TBAM Agent, the two variables *OFGW_ADDRESS* and *OFGW_PORT* in the TBAM Resource Manager's "islandrecurcemaneger.py" must be set to the IP address and TCP port of the SecureXMLRPC server of the TBAM Agent. 

By default, the configuration considers that both TBAM Agent and Resource Manager reside on the same machine (*OFGW_ADDRESS = "127.0.0.1"*) and the TCP port used for the communication is 8234 (*OFGW_PORT = 8234*).

The TBAM-Agent uses the Management Plane module to retrieve network details such as DPIDs of the devices and links. For testing purposes, this connection is disabled by default and the TBAM-Agent is configured to return fake information.  The connection to the Management Plane module can be enabled/disabled by changing the CONN_WITH_MGMT parameter to True/False in the src/main.py. Obviously, the activation of this connection requires the Management Plane to be installed, configured and started (see [OFGW_MGMT](https://github.com/fp7-alien/OCF-OFGW/tree/master/ofgw_mngt))

##User's authentication
On the OFGW, both users/experimenters and administrators can use the Management interface of the devices to perform custom configurations or to retrieve the current status. The access is guaranteed by the local LDAP client which is connected to the central OFELIA LDAP server to allow the users SSH access using the OFELIA credentials. 
While the island administrator has always access to the OFGW, normal users are allowed to login only during their experiment time-slot. The LDAP client is configured by the TBAM Agent which, in turn, receives the experiments details (e.g. project id, time-slot, etc.) from the TBAM RM. With these details, the TBAM Agent re-configures the 
LDAP client at the beginning of each time-slot so that only the authorized users are enabled to access the OFGW

###LDAP client configuration
To connect the OFGW’s LDAP client to the central OFELIA LDAP server, the following steps are required:

1. DNS bind between LDAP url and its IP address (add the line LDAP_IP_address LDAP_url to
/etc/hosts);
2. Install package ibpam-ldapd (e.g, apt-get install ibpam-ldapd) and follow the procedure on the 
UI to configure the package. When required:
a. Insert the LDAP url (ldap://ldap.ibbt.fp7-ofelia.eu)
b. Set the correct DN (dc=fp7-ofelia,dc=eu)
c. Select not to root management
d. Authorize the modification of nsswitch.conf: check that passwd,group,netgroup are 
selected.
3. Add auth required pam_access.so in /etc/pam.d/common-auth
4. Add session required pam_mkhomedir.so skel=/etc/skel umask=0022 in 
/etc/pam.d/common-session
5. Create file /etc/security/access.conf (e.g., touch /etc/security/access.conf) and add 
this three line: 

```
+ : ALL : LOCAL 
+ : @proj_<project_UUID>_<project_name> : ALL
- : EXCEPT root login:ALL EXCEPT LOCAL
```
After the configuration, the root user is able to login through a SSH connection. Other users can authenticate only if both 
TBAM Agent and TBAM RM are up and running and the users are associated to the current experiment. 

 
###Configuration interface
The TBAM Agent receives the LDAP configuration parameters through the following interface:
Set/remUserAuth(projectInfo): respectively write or clear the projectInfo in the /etc/access.conf file. The projectInfo containts project_UUID and project_name and allows to query the LDAP server to authenticate only the permitted users.<commit_msg>README: Installation procedure updated<commit_after>#The TBAM Agent
The TBAM Agent is a daemon running on the OpenFlow Gateway (OFGW) and is responsible for the configuration Management Plane, Control Plane and Data Plane. OFGW is deployed as a Debian 6 Linux machine (real or virtual) and is configured/controlled by the TBAM Agent daemon. Regarding the Management plane, TBAM Agent permits not only to manage the configuration of the network devices, but also to retrieve the information of the forwarding plane thanks to pre-defined functionalities exposed by the Management plane. Moreover, the OFGW is in-charge of redirecting the Control traffic to the user controller and handling the data traffic from and to OFELIA islands. Consequently, TBAM Agent provides the configuration also of Control and Data Plane. The architecture of the OFGW is summarized in bottom port of [figure](https://wiki.man.poznan.pl/alien/img_auth.php/a/a4/Work_distribution.png).

##INSTALLATION
The communication with the [TBAM Resource Manager](https://github.com/fp7-alien/OCF-TBAM/blob/master/TBAM-RM/README.md#tbam-resource-manager) is obtained with a SecureXMLRPC interface. 
For testing purposes, the RPC server in the TBAM Agent and the TBAM RM use pre-installed certificates. In real deployments, the [ClearingHouse](http://www.eict.de/c-bas) can be used to generate the certificates. The TBAM Agent uses three certificates for the SecureXMLRPC authentication; moreover, the references contained in the code must be compliant with your local path. In particular, the parameters of the certificates used in the TBAM Agent are:

Parameter | Reference
------------- | -------------
SERVER_KEY_PATH | it refers to the server key.
SERVER_CERT_PATH |  it refers to the server cert. 
TRUSTED_CERT_PATH | it refers to trusted certificate issued by Clearinghouse.

On the other hand, in order to communicate with the TBAM Agent, the TBAM Resource Manager must use the correct client certificates defined by parameters *CLIENT_KEY_PATH* and *CLIENT_CERT_PATH* within the [Resource Manager's code](https://github.com/fp7-alien/OCF-TBAM)

The TBAM Agent can be started entering the folder OCF-OFGW/TBAM-Agent (e.g., *cd OCF-OFGW/TBAM-Agent*) and running the "src/main.py" with python (e.g., *python src/main.py*). The TBAM Agent has been tested with Python version 2.7.

To connect the Resource Manager to the TBAM Agent, the two variables *OFGW_ADDRESS* and *OFGW_PORT* in the TBAM Resource Manager's "islandrecurcemaneger.py" must be set to the IP address and TCP port of the SecureXMLRPC server of the TBAM Agent. 

By default, the configuration considers that both TBAM Agent and Resource Manager reside on the same machine (*OFGW_ADDRESS = "127.0.0.1"*) and the TCP port used for the communication is 8234 (*OFGW_PORT = 8234*).

The TBAM-Agent uses the Management Plane module to retrieve network details such as DPIDs of the devices and links. For testing purposes, this connection is disabled by default and the TBAM-Agent is configured to return fake information.  The connection to the Management Plane module can be enabled/disabled by changing the CONN_WITH_MGMT parameter to True/False in the src/main.py. Obviously, the activation of this connection requires the Management Plane to be installed, configured and started (see [OFGW_MGMT](https://github.com/fp7-alien/OCF-OFGW/tree/master/ofgw_mngt))

##User's authentication
On the OFGW, both users/experimenters and administrators can use the Management interface of the devices to perform custom configurations or to retrieve the current status. The access is guaranteed by the local LDAP client which is connected to the central OFELIA LDAP server to allow the users SSH access using the OFELIA credentials. 
While the island administrator has always access to the OFGW, normal users are allowed to login only during their experiment time-slot. The LDAP client is configured by the TBAM Agent which, in turn, receives the experiments details (e.g. project id, time-slot, etc.) from the TBAM RM. With these details, the TBAM Agent re-configures the 
LDAP client at the beginning of each time-slot so that only the authorized users are enabled to access the OFGW

###LDAP client configuration
To connect the OFGW’s LDAP client to the central OFELIA LDAP server, the following steps are required:

1. DNS bind between LDAP url and its IP address (add the line LDAP_IP_address LDAP_url to
/etc/hosts);
2. Install package libpam-ldapd (e.g, apt-get install ibpam-ldapd) and follow the procedure on the 
UI to configure the package. When required:
a. Insert the LDAP url (ldap://ldap.ibbt.fp7-ofelia.eu)
b. Set the correct DN (dc=fp7-ofelia,dc=eu)
c. Select not to root management
d. Authorize the modification of nsswitch.conf: check that passwd,group,netgroup are 
selected.
3. Add auth required pam_access.so in /etc/pam.d/common-auth
4. Add session required pam_mkhomedir.so skel=/etc/skel umask=0022 in 
/etc/pam.d/common-session
5. Create file /etc/security/access.conf (e.g., touch /etc/security/access.conf) and add 
this three line: 

```
+ : ALL : LOCAL 
+ : @proj_<project_UUID>_<project_name> : ALL
- : EXCEPT root login:ALL EXCEPT LOCAL
```
After the configuration, the root user is able to login through a SSH connection. Other users can authenticate only if both 
TBAM Agent and TBAM RM are up and running and the users are associated to the current experiment. 

 
###Configuration interface
The TBAM Agent receives the LDAP configuration parameters through the following interface:
Set/remUserAuth(projectInfo): respectively write or clear the projectInfo in the /etc/access.conf file. The projectInfo containts project_UUID and project_name and allows to query the LDAP server to authenticate only the permitted users.
{'fraction_non_alphanumeric': 0.0627495226523173, 'fraction_numerical': 0.0055545912168026386, 'mean_word_length': 4.610029211295034, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 8, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, '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': '3176635', 'n_tokens_mistral': 3254, 'n_tokens_neox': 3045, 'n_words': 1568}