README.md 19.1 KB
Newer Older
Marco Malavolti's avatar
Marco Malavolti committed
1
# EduGAIN Connectivity Check Service - ECCS
Marco Malavolti's avatar
Marco Malavolti committed
2

Marco Malavolti's avatar
Marco Malavolti committed
3
4
5
6
7
8
9
10
1. [Introduction](#introduction)
2. [Check Performed on the IdPs](#check-performed-on-the-idps)
3. [Limitations](#limitations)
4. [Disable Checks](#disable-checks)
5. [On-line interface](#on-line-interface)
6. [Requirements Hardware](#requirements-hardware)
7. [Requirements Software](#requirements-software)
8. [HOWTO Install and Configure](#howto-install-and-configure)
Marco Malavolti's avatar
Marco Malavolti committed
11
   * [Python 3](#python-3)
Marco Malavolti's avatar
Marco Malavolti committed
12
13
     + [CentOS 7 requirements](#centos-7-requirements)
     + [Debian requirements](#debian-requirements)
Marco Malavolti's avatar
Marco Malavolti committed
14
15
16
17
18
19
20
21
22
23
24
25
     + [Install](#install)
   * [Install the Chromedriver](#install-the-chromedriver)
   * [Install Google Chrome needed by Selenium](#install-google-chrome-needed-by-selenium)
   * [ECCS Script](#eccs-script)
     + [Install](#install-1)
     + [Configure](#configure)
     + [Execute](#execute)    
9. [ECCS API Server (UWSGI)](#eccs-api-server-uwsgi)
   * [Install](#install-1)
   * [Configure](#configure-1)
   * [Utility](#utility)
10. [ECCS API JSON](#eccs-api-json)
26
27
28
29
11. [User Interface](#user-interface)
    * [User interface parameters](#user-interface-parameters)
12. [Utility for web interface](#utility-for-web-interface)
13. [Utility for developers](#utility-for-developers)
Marco Malavolti's avatar
Marco Malavolti committed
30
    * [ECCS API Development Server](#eccs-api-development-server)
31
14. [Authors](#authors)
Marco Malavolti's avatar
Marco Malavolti committed
32

33
## Introduction
Marco Malavolti's avatar
Marco Malavolti committed
34

35
The purpose of the eduGAIN Connectivity Check is to identify eduGAIN Identity Providers (IdP) that are not properly configured. In particular it checks if an IdP properly loads and consumes SAML2 metadata which contains the eduGAIN Service Providers (SP). The check results are published on the public eduGAIN Connectivity Check web page ([https://technical.edugain.org/eccs](https://technical.edugain.org/eccs)). The main purpose is to increase the service overall quality and user experience of the eduGAIN interfederation service by making Federation and Identity Provider operators aware of configuration problems.
Marco Malavolti's avatar
Marco Malavolti committed
36

Marco Malavolti's avatar
Marco Malavolti committed
37
The check is performed by sending a SAML authentication request to each eduGAIN IdP and then follow the various HTTP redirects until the user login form. The expected result is a login form that allows users to authenticate themselves (typically with username/password) or an error message of some form. For those Identity Providers that return an error message, it can be assumed that they don't consume eduGAIN metadata properly or that they suffer from another configuration problem. There are some cases where the check will generate false positives, therefore IdPs can be excluded from checks as is described below.
Marco Malavolti's avatar
Marco Malavolti committed
38
39
40

The Identity Providers are checked once per day. Therefore, the login requests should not have any significant effect on the log entries/statistics of an Identity Provider. Also, no actual login is performed because the check cannot authenticate users due to missing username and password for the IdPs. Only Identity Providers are checked but not the Service Providers.

41
## Check Performed on the IdPs
Marco Malavolti's avatar
Marco Malavolti committed
42

43
The check follows the steps:
Marco Malavolti's avatar
Marco Malavolti committed
44
45
46

1. It retrieves the eduGAIN IdPs from eduGAIN Operator Team database via a JSON interface

Marco Malavolti's avatar
Marco Malavolti committed
47
48
49
2. For each IdP, that hasn't been disabled manually by the eduGAIN Operations Team or dynamically by `robots.txt` (explained below) and that has a valid SSL certificate on its HTTP-Redirect Location, it performs an IdP-initiated SSO with SAML Authentication Request for two SP belonging two different NREN, members of eduGAIN interfederation, and for another randomnly generated fake SP. It expects to find the HTML form with username and password fields for the NREN SPs and an error or other result for the fake one. If an IdP uses frames on the Login page, the check follows only the first one on each nested pages. If an IdP uses HTTP Basic Authentication, the check searches '401 Unauthorized' string into the web page content returned or 401 HTTP Status Code from the request. Therefore, no complete login will happen at the Identity Provider because the check stops at the login page.
The SAML Authentication Request is not signed. Therefore, an authentication request for any eduGAIN SP could be created because the SP's private key is not needed.
The SPs HTTP-Post Assertion Consumer Service URLs used by the check are retrieved by `sps-metadata.xml` frile from the "input" directory. The 'validation' method used to validate the "sps-metadata.xml" is a deployer decision, but a solution is provided on the `README-SPS-METADATA.md` file.
Marco Malavolti's avatar
Marco Malavolti committed
50

Marco Malavolti's avatar
Marco Malavolti committed
51
3. If the check fails for an IdP the first time, a second attempt will be done at the end of all other checked IdP, before exit.
52

Marco Malavolti's avatar
Marco Malavolti committed
53
4. The results are kept for the last 7 days, but the deployers can increase it as they wish.
54
55

## Limitations
Marco Malavolti's avatar
Marco Malavolti committed
56
57
58

There are some situations where the check cannot work reliably. In those cases it is possible to disable the check for a particular IdP. The so far known cases where the check might generate a false negative are:

Marco Malavolti's avatar
Marco Malavolti committed
59
* IdP does not support HTTPS with at least SSLv3 or TLS1 or newer (these IdPs are insecure anyway)
Marco Malavolti's avatar
Marco Malavolti committed
60
* IdP is part of a Hub & Spoke federation (some of them manually have to first approve eduGAIN SPs)
61
* IdP does not use web-based login form (e.g. Account Chooser Authentication or X.509 login)
Marco Malavolti's avatar
Marco Malavolti committed
62

63
## Disable Checks
Marco Malavolti's avatar
Marco Malavolti committed
64

65
In cases where an IdP cannot be reliably checked, it is necessary to create or enrich the `robots.txt` file on the IdP's web root dir with:
66
67
68
69
70

```bash
User-agent: ECCS
Disallow: /
```
Marco Malavolti's avatar
Marco Malavolti committed
71

Marco Malavolti's avatar
Marco Malavolti committed
72
If an IdP is not able to create its own `robots.txt`, it can be disabled by an eduGAIN Operation Team member by setting the dictionary `IDPS_DISABLED_DICT` into `eccs_properties.py` with a line like:
Marco Malavolti's avatar
Marco Malavolti committed
73

Marco Malavolti's avatar
Marco Malavolti committed
74
`<idp-entity-id>':'<eccs-check-disabling-reason>`
Marco Malavolti's avatar
Marco Malavolti committed
75
76


77
## On-line interface
Marco Malavolti's avatar
Marco Malavolti committed
78
79
80
81

The tool uses following status for IdPs:

* ERROR (red):
Marco Malavolti's avatar
Marco Malavolti committed
82
  * The IdP's response contains an error or the web page is not returned due a Timeout, Connection or IdP Generic error.
Marco Malavolti's avatar
Marco Malavolti committed
83
    * **Timeout**: considers those IdPs that do not load a standard username/password login page within 60 seconds.
Marco Malavolti's avatar
Marco Malavolti committed
84
85
    * **Connection-Error**: considers those IdPs that are not reachable due to a connection problem. View the "Page Source" content to discover which problem has the IdP. 
    * **IdP-Generic-Error**: considers those IdPs that the returned web page does not contain a Login Form, but an unspecified error such as "*An error occured*". This kind of error has been seen on Micrsoft ADFS based IdPs.
Marco Malavolti's avatar
Marco Malavolti committed
86
  * The IdP most likely does not consume the eduGAIN metadata correctly.
Marco Malavolti's avatar
Marco Malavolti committed
87
88
    * **No-SP-Metadata-Error**: considers those IdPs that returns a message like "*No return endpoint available for relying party*" or "*No metadata found for relying party*" instead of the Login Page.
  * The IdP has an SSL problem on the HTTP-Redirect Location used by the check:
Marco Malavolti's avatar
Marco Malavolti committed
89
    * **SSL-Error**
Marco Malavolti's avatar
Marco Malavolti committed
90
* OK (green):
Marco Malavolti's avatar
Marco Malavolti committed
91
92
93
94
  * The IdP most likely correctly consumes eduGAIN metadata and returns a valid username/password login page. This is no guarantee that login on this IdP works for all eduGAIN services but if the check is passed for an IdP, this is probable.
* UNKNOWN (grey):
  * The IdP can't be checked because the returned Login Page content is not recognized or the Login Page is always returned, also for the fake SP.
    * **Unable-To-Check**: considers those IdPs that do not load a standard username/password login page and do not return messages like "*No return endpoint available for relying party*" or "*No metadata found for relying party"*.
Marco Malavolti's avatar
Marco Malavolti committed
95
* DISABLED (white)
Marco Malavolti's avatar
Marco Malavolti committed
96
97
  * The IdP is excluded because it cannot be checked reliably. The "*Page Source*" column content, when an entity is disabled, shows the reason of the disabling.
   * **Disabled**: considers those IdPs that are disabled from the check by an eduGAIN Operator or "robots.txt" file.
Marco Malavolti's avatar
Marco Malavolti committed
98

99
## Requirements Hardware
100

Marco Malavolti's avatar
Marco Malavolti committed
101
* OS: Debian 11, CentOS 7.8 (tested)
102
103
* HDD: 10 GB
* RAM: 4 GB
104
* CPU: >= 2 vCPU (suggested)
Marco Malavolti's avatar
Marco Malavolti committed
105
* ARCH: 64 Bit
106

107
## Requirements Software
108
109

* Apache Server + WSGI
110
* Python 3 (tested with v3.9.1, v3.10.4)
Marco Malavolti's avatar
Marco Malavolti committed
111
112
* Selenium (tested with v4.1.3)
* Google Chrome Web Brower (tested with v91.0.4472.164, v100.0.4896.127, v101.0.4951.64)
113
* Chromedriver (tested with v91.0.4472.101, v100.0.4896.60)
Marco Malavolti's avatar
Marco Malavolti committed
114
* Git
115
* PHP
116

117
## HOWTO Install and Configure
118

119
### Download ECCS Repository
120

Marco Malavolti's avatar
Marco Malavolti committed
121
* `cd $HOME ; git clone https://gitlab.geant.org/edugain/eccs.git`
122

123
### Install Python 3
Marco Malavolti's avatar
Marco Malavolti committed
124

125
#### CentOS 7 requirements
Marco Malavolti's avatar
Marco Malavolti committed
126
127
128
129

1. Update the system packages:
   * `sudo yum -y update`

130
131
2. Install the YUM utils:
   * `sudo yum install yum-utils`
Marco Malavolti's avatar
Marco Malavolti committed
132
133

3. Install needed packages to build python:
134
   * `sudo yum-builddep python3`
Marco Malavolti's avatar
Marco Malavolti committed
135

136
137
138
139
140
141
142
   If you want to use Python 3.10, you need OpenSSL >= 1.1.1:
   * `sudo yum install openssl11 openssl11-devel`
   * `sudo mkdir /usr/local/openssl11`
   * `sudo cd /usr/local/openssl11`
   * `sudo ln -s /usr/lib64/openssl11 lib`
   * `sudo ln -s /usr/include/openssl11 include`

Marco Malavolti's avatar
Marco Malavolti committed
143
144
145
4. Install Git:
   * `sudo yum -y install git`

146
#### Debian requirements
147
148
149
150

1. Update the system packages:
   * `sudo apt update ; sudo apt upgrade -y`

151
2. Install needed packages to build python3:
152
   * `sudo apt-get build-dep python3 libffi-dev libssl-dev zlib-dev`
153

Marco Malavolti's avatar
Marco Malavolti committed
154
155
156
3. Install Git:
   * `sudo apt install git`

157
#### Install
158

Marco Malavolti's avatar
Marco Malavolti committed
159
1. Download the last version of Python 3 from https://www.python.org/downloads/source/ into your home:
160
   * `wget https://www.python.org/ftp/python/3.10.4/Python-3.10.4.tgz -O $HOME/eccs/Python-3.10.4.tgz`
161

Marco Malavolti's avatar
Marco Malavolti committed
162
2. Extract Python source package:
Marco Malavolti's avatar
Marco Malavolti committed
163
   * `cd $HOME/eccs/`
164
   * `tar xzf Python-3.10.4.tgz`
165

Marco Malavolti's avatar
Marco Malavolti committed
166
3. Build Python from the source package:
167
168
169
170
171
172
173
174
175
   * Debian:
     * `cd $HOME/eccs/Python-3.10.4`
     * `./configure --prefix=$HOME/eccs/python`
     * `make`

   * Centos 7:
     * `cd $HOME/eccs/Python-3.10.4`
     * `./configure --prefix=$HOME/eccs/python --with-openssl=/usr/local/openssl11`
     * `make`
176

Marco Malavolti's avatar
Marco Malavolti committed
177
4. Install Python 3 under `$HOME/eccs/python`:
178
   * `make install`
Marco Malavolti's avatar
Marco Malavolti committed
179
   * `$HOME/eccs/python/bin/python3 --version`
180
   * `$HOME/eccs/python/bin/python3 -c "import ssl; print (ssl.OPENSSL_VERSION)"`
181
 
182
   This will install python3 under your $HOME/eccs/python directory.
183
184
   
5. Remove useless things:
185
   * `rm -Rf $HOME/eccs/Python-3.10.4 $HOME/eccs/Python-3.10.4.tgz`
186

187
### Install Google Chrome needed by Selenium
188

Marco Malavolti's avatar
Marco Malavolti committed
189
* Debian (64 bit):
Marco Malavolti's avatar
Marco Malavolti committed
190
  * `cd $HOME/eccs`
Marco Malavolti's avatar
Marco Malavolti committed
191
192
  * `sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb`
  * `sudo apt install ./google-chrome-stable_current_amd64.deb`
Marco Malavolti's avatar
Marco Malavolti committed
193

Marco Malavolti's avatar
Marco Malavolti committed
194
* CentOS (64 bit):
Marco Malavolti's avatar
Marco Malavolti committed
195
  * `cd $HOME/eccs`
Marco Malavolti's avatar
Marco Malavolti committed
196
197
  * `sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm`
  * `sudo yum install ./google-chrome-stable_current_x86_64.rpm`
198

199
### Install the Chromedriver
200

Marco Malavolti's avatar
Marco Malavolti committed
201
202
1. Find out which version of Chromium you are using:
   * Debian 9 (stretch):
203
     * `google-chrome -version` => Google Chrome 100.0.4896.127
Marco Malavolti's avatar
Marco Malavolti committed
204
   * CentOS 7.8:
205
     * `google-chrome -version` => Google Chrome 100.0.4896.127
Marco Malavolti's avatar
Marco Malavolti committed
206

207
2. Take the Chrome version number, remove the last part, and append the result to URL "`https://chromedriver.storage.googleapis.com/LATEST_RELEASE_`". For example, with Chrome version 100.0.4896.127, you'd get a URL "`https://chromedriver.storage.googleapis.com/LATEST_RELEASE_100.0.4896`".
Marco Malavolti's avatar
Marco Malavolti committed
208

209
3. Use the URL created in the last step to discover the version of ChromeDriver to use. For example, the above URL will get your a file containing "100.0.4896.60".
Marco Malavolti's avatar
Marco Malavolti committed
210

211
4. Use the version number retrieved from the previous step to construct the URL to download ChromeDriver. With version `100.0.4896.60`, the URL would be "https://chromedriver.storage.googleapis.com/index.html?path=100.0.4896.60/"
212

Marco Malavolti's avatar
Marco Malavolti committed
213
5. Download the Chromedriver and extract it with:
Marco Malavolti's avatar
Marco Malavolti committed
214
   * `cd $HOME/eccs`
215
   * `wget https://chromedriver.storage.googleapis.com/100.0.4896.60/chromedriver_linux64.zip`
Marco Malavolti's avatar
Marco Malavolti committed
216
   * `unzip chromedriver_linux64.zip`
Marco Malavolti's avatar
Marco Malavolti committed
217
   * `rm chromedriver_linux64.zip google-chrome-stable_current_amd64.deb`
Marco Malavolti's avatar
Marco Malavolti committed
218
219
220

**Note:**
After the initial download, it is recommended that you occasionally go through the above process again to see if there are any bug fix releases.
221

222
### ECCS Script
Marco Malavolti's avatar
Marco Malavolti committed
223

224
#### Install and Configure the Virtual Environment
Marco Malavolti's avatar
Marco Malavolti committed
225

Marco Malavolti's avatar
Marco Malavolti committed
226
227
228
229
230
231
* `cd $HOME/eccs`
* `./python/bin/python3 -m pip install virtualenv`
* `$HOME/eccs/python/bin/virtualenv --python=$HOME/eccs/python/bin/python3 eccs-venv`
* `$HOME/eccs/eccs-venv/bin/python3 -m pip install --upgrade pip`
* `source eccs-venv/bin/activate`   (`deactivate` to exit Virtualenv)
  * `python3 -m pip install -r requirements.txt`
232

233
#### Configure ECCS
234

Marco Malavolti's avatar
Marco Malavolti committed
235
1. Configure ECCS properties:
236
237
   * `cp $HOME/eccs/eccs_properties.py.template $HOME/eccs/eccs_properties.py`
   * `vim $HOME/eccs/eccs_properties.py` (and change it upon your needs)
238

239
2. Change `PATH` by adding the virtualenv Python `bin` dir:
240
241
   * CentOS:
     * `vim $HOME/.bash_profile`
Marco Malavolti's avatar
Marco Malavolti committed
242
243
244
     * Add the following lines at the tail:
       
       ```bash
Marco Malavolti's avatar
Marco Malavolti committed
245
       # set PATH for ECCS
246
       if [ -d "$HOME/eccs" ]; then
Marco Malavolti's avatar
Marco Malavolti committed
247
          PATH="$HOME/eccs/eccs-venv/bin:$PATH"
Marco Malavolti's avatar
Marco Malavolti committed
248
249
250
       fi
       ```

Marco Malavolti's avatar
Marco Malavolti committed
251
252
     * `source $HOME/.bash_profile`

253
   * Debian:
Marco Malavolti's avatar
Marco Malavolti committed
254
     * `vim $HOME/.bash_profile`
Marco Malavolti's avatar
Marco Malavolti committed
255
256
257
     * Add the following lines at the tail:
       
       ```bash
Marco Malavolti's avatar
Marco Malavolti committed
258
       # set PATH for ECCS
259
       if [ -d "$HOME/eccs" ]; then
Marco Malavolti's avatar
Marco Malavolti committed
260
          PATH="$HOME/eccs/eccs-venv/bin:$PATH"
Marco Malavolti's avatar
Marco Malavolti committed
261
262
263
       fi
       ```

Marco Malavolti's avatar
Marco Malavolti committed
264
265
     * `source $HOME/.bash_profile`

Marco Malavolti's avatar
Marco Malavolti committed
266
3. Configure the cron job that runs the ECCS script:
267
   * `crontab -e`
268

269
     ```bash
Marco Malavolti's avatar
Marco Malavolti committed
270
271
     SHELL=/bin/bash

Marco Malavolti's avatar
Marco Malavolti committed
272
     0 4 * * * /bin/bash $HOME/eccs/cleanAndRunEccs.sh > $HOME/eccs/logs/eccs-cron.log 2>&1
273
     ```
Marco Malavolti's avatar
Marco Malavolti committed
274

Marco Malavolti's avatar
Marco Malavolti committed
275
276
277
     The script takes about 2 hours to check 4666 IDPs, so its execution is suggested in the early morning,before the users start using the tool. 
     The `eccs-cron.log` file will contains:
        * The execution time of the entire ECCS script
Marco Malavolti's avatar
Marco Malavolti committed
278
279
        * Each failed IdP checked again and their results
        * The result of the entire ECCS script
Marco Malavolti's avatar
Marco Malavolti committed
280

281
### Execute
282

Marco Malavolti's avatar
Marco Malavolti committed
283
284
285
286
287
288
289
  * `cd $HOME/eccs`
  * `./cleanAndRunEccs.py` (to run a full and clean check)
  * `./runEccs.py` (to run a full check on the existing inputs)
  * `./runEccs.py --idp <IDP-ENTITYID>` (to run check on a single IdP)
  * `./runEccs.py --test` (to run a full check without effects)
  * `./runEccs.py --idp <IDP-ENTITYID> --test` (to run check on a single IdP without effects)
  * `./runEccs.py --idp <IDP-ENTITYID> --replace` (to run check on a single IdP and replace, or add, a result)
290

Marco Malavolti's avatar
Marco Malavolti committed
291
  If something prevent the good execution of the ECCS's check, the `logs/failed-cmd.sh` file will be not empty at the end of the execution.
Marco Malavolti's avatar
Marco Malavolti committed
292

Marco Malavolti's avatar
Marco Malavolti committed
293
  The "--test" parameter will not change the result of ECCS, but will write the output on the `logs/stdout_idp_YYYY-MM-DD.log`,`logs/stderr_idp_YYYY-MM-DD.log` and `logs/failed-cmd-idp.sh` files if the argument "--test" will be used.
Marco Malavolti's avatar
Marco Malavolti committed
294

295
## ECCS API Server (uWSGI)
Marco Malavolti's avatar
Marco Malavolti committed
296

297
### Install
Marco Malavolti's avatar
Marco Malavolti committed
298

299
300
301
302
303
1. Install requirements:
   * Debian:
     * `sudo apt-get install libpcre3 libpcre3-dev libapache2-mod-proxy-uwsgi build-essentials python3-dev unzip`
   * CentOS:
     * `sudo yum install mod_proxy_uwsgi unzip`
Marco Malavolti's avatar
Marco Malavolti committed
304
     * Configure SElinux to enable ECCS:
Marco Malavolti's avatar
Marco Malavolti committed
305
       * `sudo semanage fcontext -a -t httpd_sys_content_t $HOME/eccs/eccs.conf`
Marco Malavolti's avatar
Marco Malavolti committed
306
       * `sudo restorecon -v $HOME/eccs/eccs.conf`
Marco Malavolti's avatar
Marco Malavolti committed
307
       * `sudo semanage fcontext -a -t httpd_sys_content_t $HOME/eccs/html(/.*)?`
Marco Malavolti's avatar
Marco Malavolti committed
308
       * `sudo restorecon -R -v "$HOME/eccs/html/"`
309
310
       * `sudo setsebool -P httpd_can_network_connect 1`
 
311
### Configure
Marco Malavolti's avatar
Marco Malavolti committed
312

Marco Malavolti's avatar
Marco Malavolti committed
313
314
315
316
317
318
319
1. Add the systemd service to enable ECCS API:
   * `cd $HOME/eccs`
   * `cp eccs.ini.template eccs.ini`
   * `cp eccs.service.template eccs.service`
   * `vim eccs.ini` (and change "`uid`", "`gid`" and "`base`" values opportunely)
   * `vim eccs.service` (and change "`User`","`Group`","`WorkingDirectory`","`RuntimeDirectory`","`ExecStart`" values opportunely)
   * `sudo cp $HOME/eccs/eccs.service /etc/systemd/system/eccs.service`
320
   * `sudo systemctl daemon-reload`
Marco Malavolti's avatar
Marco Malavolti committed
321
322
   * `sudo systemctl enable eccs.service`
   * `sudo systemctl start eccs.service`
323

Marco Malavolti's avatar
Marco Malavolti committed
324
2. Configure Apache for ECCS web side:
325
   * Debian:
Marco Malavolti's avatar
Marco Malavolti committed
326
     * `sudo cp $HOME/eccs/eccs-debian.conf /etc/apache2/conf-available/eccs.conf`
327
     * `sudo vim /etc/apache2/conf-available/eccs.conf` (and change the file opportunely)
Marco Malavolti's avatar
Marco Malavolti committed
328
     * `sudo a2enconf eccs.conf`
329
     * `sudo a2enmod proxy_uwsgi`
330
331
332
     * `sudo chgrp www-data $HOME ; sudo chmod g+rx $HOME` (Apache needs permission to access the $HOME dir)
     * `sudo systemctl restart apache2.service`
   * CentOS:
Marco Malavolti's avatar
Marco Malavolti committed
333
     * `sudo cp $HOME/eccs/eccs-centos.conf /etc/httpd/conf.d/eccs.conf`
334
335
     * `sudo chgrp apache $HOME ; sudo apache g+rx $HOME` (Apache needs permission to access the $HOME dir)
     * `sudo systemctl restart httpd.service`
336

Marco Malavolti's avatar
Marco Malavolti committed
337
3. Restart API WSGI server each day before the ECCS script:
338
339
   * `crontab -e`

Marco Malavolti's avatar
Marco Malavolti committed
340
341
     ```bash
     SHELL=/bin/bash
342

Marco Malavolti's avatar
Marco Malavolti committed
343
344
     0 3 * * * /usr/bin/touch $HOME/eccs/eccs.ini
     ```
345

Marco Malavolti's avatar
Marco Malavolti committed
346
     This cron job must be executed prior to the ECCS script because it updates the date to the current day.
Marco Malavolti's avatar
Marco Malavolti committed
347

348
### Utility
349
350
351

To perform a restart after an API change use the following command:

Marco Malavolti's avatar
Marco Malavolti committed
352
* `touch $HOME/eccs/eccs.ini`
353

354
## ECCS API JSON
355

356
* `/api/eccsresults` (Return the results of the last check ready for ECCS web interface)
Marco Malavolti's avatar
Marco Malavolti committed
357
* `/api/eccsresults?<parameter1>=<value1>&<parameter2>=<value2>`:
358
  * `date=2020-02-20` (select date)
Marco Malavolti's avatar
Marco Malavolti committed
359
  * `idp=https://idp.example.org/idp/shibboleth` (select a specific idp)
Marco Malavolti's avatar
Marco Malavolti committed
360
  * `status=` (select specific ECCS status)
361
362
363
    * 'OK'
    * 'ERROR'
    * 'DISABLED'
Marco Malavolti's avatar
Marco Malavolti committed
364
    * 'UNKNOWN'
Marco Malavolti's avatar
Marco Malavolti committed
365
366
367
368
  * `check_result=`
    * `OK`
    * `Timeout`
    * `Connection-Error`
Marco Malavolti's avatar
Marco Malavolti committed
369
370
    * `IdP-Generic-Error`
    * `No-SP-Metadata-Error`
Marco Malavolti's avatar
Marco Malavolti committed
371
    * `SSL-Error`
372
    * `Unable-To-Check`
Marco Malavolti's avatar
Marco Malavolti committed
373
    * `Disabled`
374
  * `reg_auth=https://reg.auth.example.org` (select a specific Registration Authority)
375
  * `format=simple` (retrieve results in a simple format)
Marco Malavolti's avatar
Marco Malavolti committed
376
377
* `/api/fedstats?<parameter1>=<value1>&<parameter2>=<value2>`
  * `reg_auth=https://reg.auth.example.org`:
378

Marco Malavolti's avatar
Marco Malavolti committed
379
## User interface
380

Marco Malavolti's avatar
Marco Malavolti committed
381
The eduGAIN Connectivity Check Service web page is available at ([https://technical.edugain.org/eccs](https://technical.edugain.org/eccs))
Marco Malavolti's avatar
Marco Malavolti committed
382

383
### User interface parameters
Marco Malavolti's avatar
Marco Malavolti committed
384
385
386
387
388
389
390
391
392
393
394

| Parameter name | Example                                      |
| -------------- | -------------------------------------------- |
| `date`         | `date=2020-02-20`                            |
| `reg_auth`     | `reg_auth=https://reg.auth.example.org`      |
| `idp`          | `idp=https://idp.example.org/idp/shibboleth` |
| `status`       | `status=ERROR`                               |
| `check_result` | `check_result=Timeout`                       |

**Example:**

Marco Malavolti's avatar
Marco Malavolti committed
395
`https://technical.edugain.org/eccs?reg_auth=http://www.idem.garr.it/&check_result=SSL-Error`
Marco Malavolti's avatar
Marco Malavolti committed
396

397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
## Utility for web interface

The available dates are provided by the first and the last file created into the `output/` directory,
remember to change its path into `web/eccs.php` file.

### Clean old results

To clean the ECCS results from files older than last 7 days use (modify it on your needs):

* `crontab -e`

  ```bash
  SHELL=/bin/bash

  0 10 * * * /bin/bash $HOME/eccs/clean7daysOldFiles.sh > $HOME/eccs/logs/clean7daysOldFiles.log 2>&1  
  ```

Marco Malavolti's avatar
Marco Malavolti committed
414
  This cron job is useful to reduce the considered days selectable on the ECCS Web GUI calendar.
Marco Malavolti's avatar
Marco Malavolti committed
415

Marco Malavolti's avatar
Marco Malavolti committed
416
  It is suggested to configure it after the execution of ECCS script to get the hoped result.
Marco Malavolti's avatar
Marco Malavolti committed
417

418
## Utility for developers
419

420
### ECCS API Development Server
421

Marco Malavolti's avatar
Marco Malavolti committed
422
* `cd $HOME/eccs ; ./api.py`
423

424
### Search files created on the current date
Marco Malavolti's avatar
Marco Malavolti committed
425
426
427
428

* `cd $HOME/eccs`
* `find . -name *$(date +%Y-%m-%d)*`

429
### Delete files created on the current date
Marco Malavolti's avatar
Marco Malavolti committed
430
431
432
433

* `cd $HOME/eccs`
* `rm -rf html/$(date +%Y-%m-%d) output/eccs_$(date +%Y-%m-%d).log logs/*_$(date +%Y-%m-%d).log`

434
## Authors
Marco Malavolti's avatar
Marco Malavolti committed
435

436
### Original Author
Marco Malavolti's avatar
Marco Malavolti committed
437
438

 * Marco Malavolti (marco.malavolti@garr.it)
Marco Malavolti's avatar
Marco Malavolti committed
439
440
441
442

### GUI Developers

 * Valentin Pocotilenco (valentin.pocotilenco@renam.md)