README.md 19.3 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)
62
63
* IdP does not allow requests coming from the ECCS servers: technical-test.edugain.org / technical.edugain.org
* IdP that uses more than one nested `<iframe>` inside the login page.
Marco Malavolti's avatar
Marco Malavolti committed
64

65
## Disable Checks
Marco Malavolti's avatar
Marco Malavolti committed
66

67
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:
68
69
70
71
72

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

Marco Malavolti's avatar
Marco Malavolti committed
74
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
75

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


79
## On-line interface
Marco Malavolti's avatar
Marco Malavolti committed
80
81
82
83

The tool uses following status for IdPs:

* ERROR (red):
84
85
86
87
  * The IdP's response contains an error or the web page is not returned due to a Timeout, Connection or IdP Generic error.
    * **Timeout**: considers those IdPs that do not load a standard username/password login page <u>within 60 seconds</u>.
    * **Connection-Error**: considers those IdPs that are not reachable due to a connection problem. View the "<u>Page Source</u>" 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 Microsoft ADFS based IdPs.
Marco Malavolti's avatar
Marco Malavolti committed
88
  * The IdP most likely does not consume the eduGAIN metadata correctly.
89
90
    * **No-SP-Metadata-Error**: considers those IdPs that return a message like "*No return endpoint available for relying party*" or "*No metadata found for relying party*" instead of the Login Page.
  * The HTTP SSL certificate used by the IdP is invalid:
Marco Malavolti's avatar
Marco Malavolti committed
91
    * **SSL-Error**
Marco Malavolti's avatar
Marco Malavolti committed
92
* OK (green):
Marco Malavolti's avatar
Marco Malavolti committed
93
94
95
96
  * 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
97
* DISABLED (white)
98
99
  * The IdP is excluded because it cannot be checked reliably. The "<u>Page Source</u>" column, when an entity is disabled, is populated with the reason for the disabling.
   * **Disabled**: considers those IdPs that are disabled from the check by an eduGAIN Operation Team member or "*robots.txt*" file.
Marco Malavolti's avatar
Marco Malavolti committed
100

101
## Requirements Hardware
102

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

109
## Requirements Software
110
111

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

119
## HOWTO Install and Configure
120

121
### Download ECCS Repository
122

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

125
### Install Python 3
Marco Malavolti's avatar
Marco Malavolti committed
126

127
#### CentOS 7 requirements
Marco Malavolti's avatar
Marco Malavolti committed
128
129
130
131

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

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

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

138
139
140
141
142
143
144
   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
145
146
147
4. Install Git:
   * `sudo yum -y install git`

148
#### Debian requirements
149
150
151
152

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

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

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

159
#### Install
160

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

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

Marco Malavolti's avatar
Marco Malavolti committed
168
3. Build Python from the source package:
169
170
171
172
173
174
175
176
177
   * 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`
178

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

189
### Install Google Chrome needed by Selenium
190

Marco Malavolti's avatar
Marco Malavolti committed
191
* Debian (64 bit):
Marco Malavolti's avatar
Marco Malavolti committed
192
  * `cd $HOME/eccs`
Marco Malavolti's avatar
Marco Malavolti committed
193
194
  * `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
195

Marco Malavolti's avatar
Marco Malavolti committed
196
* CentOS (64 bit):
Marco Malavolti's avatar
Marco Malavolti committed
197
  * `cd $HOME/eccs`
Marco Malavolti's avatar
Marco Malavolti committed
198
199
  * `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`
200

201
### Install the Chromedriver
202

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

209
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
210

211
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
212

213
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/"
214

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

**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.
223

224
### ECCS Script
Marco Malavolti's avatar
Marco Malavolti committed
225

226
#### Install and Configure the Virtual Environment
Marco Malavolti's avatar
Marco Malavolti committed
227

Marco Malavolti's avatar
Marco Malavolti committed
228
229
230
231
232
233
* `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`
234

235
#### Configure ECCS
236

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

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

Marco Malavolti's avatar
Marco Malavolti committed
253
254
     * `source $HOME/.bash_profile`

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

Marco Malavolti's avatar
Marco Malavolti committed
266
267
     * `source $HOME/.bash_profile`

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

271
     ```bash
Marco Malavolti's avatar
Marco Malavolti committed
272
273
     SHELL=/bin/bash

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

Marco Malavolti's avatar
Marco Malavolti committed
277
278
279
     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
280
281
        * Each failed IdP checked again and their results
        * The result of the entire ECCS script
Marco Malavolti's avatar
Marco Malavolti committed
282

283
### Execute
284

Marco Malavolti's avatar
Marco Malavolti committed
285
286
287
288
289
290
291
  * `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)
292

Marco Malavolti's avatar
Marco Malavolti committed
293
  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
294

Marco Malavolti's avatar
Marco Malavolti committed
295
  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
296

297
## ECCS API Server (uWSGI)
Marco Malavolti's avatar
Marco Malavolti committed
298

299
### Install
Marco Malavolti's avatar
Marco Malavolti committed
300

301
302
303
304
305
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
306
     * Configure SElinux to enable ECCS:
Marco Malavolti's avatar
Marco Malavolti committed
307
       * `sudo semanage fcontext -a -t httpd_sys_content_t $HOME/eccs/eccs.conf`
Marco Malavolti's avatar
Marco Malavolti committed
308
       * `sudo restorecon -v $HOME/eccs/eccs.conf`
Marco Malavolti's avatar
Marco Malavolti committed
309
       * `sudo semanage fcontext -a -t httpd_sys_content_t $HOME/eccs/html(/.*)?`
Marco Malavolti's avatar
Marco Malavolti committed
310
       * `sudo restorecon -R -v "$HOME/eccs/html/"`
311
312
       * `sudo setsebool -P httpd_can_network_connect 1`
 
313
### Configure
Marco Malavolti's avatar
Marco Malavolti committed
314

Marco Malavolti's avatar
Marco Malavolti committed
315
316
317
318
319
320
321
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`
322
   * `sudo systemctl daemon-reload`
Marco Malavolti's avatar
Marco Malavolti committed
323
324
   * `sudo systemctl enable eccs.service`
   * `sudo systemctl start eccs.service`
325

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

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

Marco Malavolti's avatar
Marco Malavolti committed
342
343
     ```bash
     SHELL=/bin/bash
344

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

Marco Malavolti's avatar
Marco Malavolti committed
348
     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
349

350
### Utility
351
352
353

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

Marco Malavolti's avatar
Marco Malavolti committed
354
* `touch $HOME/eccs/eccs.ini`
355

356
## ECCS API JSON
357

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

Marco Malavolti's avatar
Marco Malavolti committed
381
## User interface
382

Marco Malavolti's avatar
Marco Malavolti committed
383
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
384

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

| 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
397
`https://technical.edugain.org/eccs?reg_auth=http://www.idem.garr.it/&check_result=SSL-Error`
Marco Malavolti's avatar
Marco Malavolti committed
398

399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
## 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
416
  This cron job is useful to reduce the considered days selectable on the ECCS Web GUI calendar.
Marco Malavolti's avatar
Marco Malavolti committed
417

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

420
## Utility for developers
421

422
### ECCS API Development Server
423

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

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

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

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

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

436
## Authors
Marco Malavolti's avatar
Marco Malavolti committed
437

438
### Original Author
Marco Malavolti's avatar
Marco Malavolti committed
439
440

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

### GUI Developers

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