Revision afd2a174
b/docs/index.md | ||
---|---|---|
1 |
DjNRO = Django + NRO (Django National Roaming Operator or how to manage your eduroam database) |
|
2 |
|
|
3 |
## About |
|
4 |
In the [eduroam](http://www.eduroam.org) world, NRO stands for National Roaming Operator. |
|
5 |
Maintaining and managing a local eduroam database is quite an important responsibility of an eduroam NRO. |
|
6 |
eduroam.org periodically polls and gathers information from all participating domains. |
|
7 |
Information is provided upstream, in a structured way (XML format) and consists of participating institutions' data, location data along with monitoring data - though provisioning of monitoring data has been superseeded by the f-Ticks mechanism. |
|
8 |
|
|
9 |
The source of information should be the local eduroam database. So, changes to the database should be reflected to the XML files. |
|
10 |
New eduroam locations, changes in contacts and information about each location should be up-to-date so as to ease the eduroam usage and assist eduroam users whenever they need support. |
|
11 |
|
|
12 |
DjNRO is a Django platform that eases the management process of a National Roaming Operator. DjNRO complies with the [eduroam database](http://monitor.eduroam.org/database.php) and the eduroam XSDs. |
|
13 |
Thus, apart from domain management, it can generate the necessary xml files for eduroam.org monitoring. |
|
14 |
|
|
15 |
DjNRO is more than keeping eduroam.org updated with data. |
|
16 |
|
|
17 |
In essence it is a distributed management application. It is distributed in the sense that information about each institution locations and services is kept up-to-date by each local eduroam administrator. Keeping in pace with eduroam's federated nature, our implementation uses federated authentication/authorisation mechanisms, namely Shibboleth. |
|
18 |
In case Shibboleth is not an option for an institution, a social media auth mechanism comes in handy. The local institution eduroam administrators can become DjNRO admins. Local eduroam administrators register to the platform via Shibboleth or social media auth. The NRO's responsibility is to activate their accounts. |
|
19 |
|
|
20 |
From then on they can manage their eduroam locations, contact points and institution information. The administrative interface especially the locations management part, is heavily implemented with Google Maps. This makes editing easier, faster and accurate. |
|
21 |
|
|
22 |
Installation and customization is fairly easy and is described in the following sections. |
|
23 |
|
|
24 |
Currently the source code is availiable at code.grnet.gr and github and can be cloned via git:: |
|
25 |
|
|
26 |
git clone https://code.grnet.gr/git/djnro |
|
27 |
git clone https://github.com/grnet/djnro.git |
|
28 |
|
|
29 |
The Greek eduroam webpage is a living example of DjNRO: `eduroam|gr <http://www.eduroam.gr>`_ |
|
30 |
|
|
31 |
## Features |
|
32 |
|
|
33 |
* Allow your local eduroam admins to edit their local eduroam data (AP locations, server params, etc) |
|
34 |
* Visualize the information via Google Maps |
|
35 |
* Eduroam world maps overview via daily update on eduroam.org KML file |
|
36 |
* Find your closest eduroam in the world |
|
37 |
* **New** Allow for eduroam CAT institution enrollments |
|
38 |
* **New** Extract contact info for mailing list creation |
|
39 |
* **New** Server monitoring data |
|
40 |
* **New** Pebble watch app with closest eduroam walking instrunctions |
|
41 |
|
|
42 |
Bootstrap 3 CSS framework with responsive design makes it work on every device |
|
43 |
|
b/docs/installation/install.md | ||
---|---|---|
1 |
# Installation/Configuration |
|
2 |
First of all you have to install all the packages described in `requirements` |
|
3 |
section |
|
4 |
|
|
5 |
The software is published at [github](https://github.com/grnet/djnro) and can be downloaded using git: |
|
6 |
|
|
7 |
git clone https://github.com/grnet/djnro |
|
8 |
|
|
9 |
|
|
10 |
## Project & Local Settings |
|
11 |
|
|
12 |
**In version 0.9 settings were split in two parts: settings.py and local_settings.py** |
|
13 |
|
|
14 |
The file settings.py contains settings distributed by the project, which should normally not be necessary to modify. |
|
15 |
Options specific to the particular installation must be configured in local_settings.py. This file must be created by copying local_settings.py.dist: |
|
16 |
|
|
17 |
cd djnro |
|
18 |
cp djnro/local_settings.py.dist djnro/local_settings.py |
|
19 |
|
|
20 |
|
|
21 |
The following variables/settings need to be altered or set: |
|
22 |
|
|
23 |
Set Admin contacts:: |
|
24 |
|
|
25 |
ADMINS = ( |
|
26 |
('Admin', 'admin@example.com'), |
|
27 |
) |
|
28 |
|
|
29 |
Set the database connection params: |
|
30 |
|
|
31 |
DATABASES = { |
|
32 |
... |
|
33 |
} |
|
34 |
|
|
35 |
For a production instance and once DEBUG is set to False set the ALLOWED_HOSTS: |
|
36 |
|
|
37 |
ALLOWED_HOSTS = ['.example.com'] |
|
38 |
SECRET_KEY = '<put something really random here, eg. %$#%@#$^2312351345#$%3452345@#$%@#$234#@$hhzdavfsdcFDGVFSDGhn>' |
|
39 |
|
|
40 |
Django social auth needs changes in the Extra Authentication Backends depending on which social auth you want to enable: |
|
41 |
|
|
42 |
EXTRA_AUTHENTICATION_BACKENDS = ( |
|
43 |
'djnro.djangobackends.shibauthBackend.shibauthBackend', |
|
44 |
... |
|
45 |
'django.contrib.auth.backends.ModelBackend', |
|
46 |
) |
|
47 |
|
|
48 |
**The default Authentication Backends are in settings.py** |
|
49 |
|
|
50 |
As the application includes a "Nearest eduroam" functionality, global eduroam service locations are harvested from the KML file published at eduroam.org:: |
|
51 |
|
|
52 |
EDUROAM_KML_URL = 'http://monitor.eduroam.org/kml/all.kml' |
|
53 |
|
|
54 |
|
|
55 |
Depending on your AAI policy set an appropriate authEntitlement:: |
|
56 |
|
|
57 |
SHIB_AUTH_ENTITLEMENT = 'urn:mace:example.com:pki:user' |
|
58 |
|
|
59 |
Mail server parameters:: |
|
60 |
|
|
61 |
SERVER_EMAIL = "Example domain eduroam Service <noreply@example.com>" |
|
62 |
EMAIL_SUBJECT_PREFIX = "[eduroam] " |
|
63 |
|
|
64 |
NRO contact mails:: |
|
65 |
|
|
66 |
NOTIFY_ADMIN_MAILS = ["mail1@example.com", "mail2@example.com"] |
|
67 |
|
|
68 |
Set your cache backend (if you want to use one). For production instances you can go with memcached. For development you can keep the provided dummy instance:: |
|
69 |
|
|
70 |
|
|
71 |
CACHES = { |
|
72 |
'default': { |
|
73 |
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', |
|
74 |
'LOCATION': '127.0.0.1:11211', |
|
75 |
} |
|
76 |
} |
|
77 |
|
|
78 |
NRO specific parameters. These affect HTML templates:: |
|
79 |
|
|
80 |
# Frontend country specific vars, eg. Greece |
|
81 |
NRO_COUNTRY_NAME = _('My Country') |
|
82 |
# Variable used by context_processor to display the "eduroam | <country_code>" in base.html |
|
83 |
NRO_COUNTRY_CODE = 'gr' |
|
84 |
# main domain url used in right top icon, eg. http://www.grnet.gr |
|
85 |
NRO_DOMAIN_MAIN_URL = "http://www.example.com" |
|
86 |
# provider info for footer |
|
87 |
NRO_PROV_BY_DICT = {"name": "EXAMPLE DEV TEAM", "url": "http://devteam.example.com"} |
|
88 |
#NRO social media contact (Use: // to preserve https) |
|
89 |
NRO_PROV_SOCIAL_MEDIA_CONTACT = [ |
|
90 |
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME1(eg. Facebook)"}, |
|
91 |
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME2(eg. Twitter)"}, |
|
92 |
] |
|
93 |
# map center (lat, lng) |
|
94 |
MAP_CENTER = (36.97, 23.71) |
|
95 |
#Helpdesk, used in base.html: |
|
96 |
NRO_DOMAIN_HELPDESK_DICT = {"name": _("Domain Helpdesk"), 'email':'helpdesk@example.com', 'phone': '12324567890', 'uri': 'helpdesk.example.com'} |
|
97 |
|
|
98 |
Set the Realm country for REALM model:: |
|
99 |
|
|
100 |
#Countries for Realm model: |
|
101 |
REALM_COUNTRIES = ( |
|
102 |
('country_2letters', 'Country' ), |
|
103 |
) |
|
104 |
|
|
105 |
Attribute map to match your AAI policy and SSO software (typically Shibboleth SP):: |
|
106 |
|
|
107 |
#Shibboleth attribute map |
|
108 |
SHIB_USERNAME = ['HTTP_EPPN'] |
|
109 |
SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL'] |
|
110 |
SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME'] |
|
111 |
SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME'] |
|
112 |
SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT'] |
|
113 |
|
|
114 |
Django Social Auth parameters: |
|
115 |
|
|
116 |
SOCIAL_AUTH_TWITTER_KEY = '' |
|
117 |
SOCIAL_AUTH_TWITTER_SECRET = '' |
|
118 |
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = '' |
|
119 |
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ' ' |
|
120 |
SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = [] |
|
121 |
|
|
122 |
|
|
123 |
DjNRO provides limited integration with eduroam CAT (Configuration Assistant Tool). Institution administrators can automatically provision their institution to CAT without the intervention of the federation (NRO) administrator. |
|
124 |
|
|
125 |
In order to enable this functionality, you must list at least one instance and the corresponding description in CAT_INSTANCES. Beware that pages accessible by end users currently only show CAT information |
|
126 |
for the instance named `production`. |
|
127 |
|
|
128 |
You must also set the following parameters for each CAT instance in CAT_AUTH: |
|
129 |
|
|
130 |
* CAT_API_KEY: API key for authentication to CAT |
|
131 |
|
|
132 |
* CAT_API_URL: API endpoint URL |
|
133 |
|
|
134 |
* CAT_PROFILES_URL: Base URL for Intitution Download Area pages |
|
135 |
|
|
136 |
* CAT_FEDMGMT_URL: URL For Federation Overview page (currently not in use) |
|
137 |
|
|
138 |
:: |
|
139 |
|
|
140 |
CAT_INSTANCES = ( |
|
141 |
('production', 'cat.eduroam.org'), |
|
142 |
('testing', 'cat-test.eduroam.org'), |
|
143 |
) |
|
144 |
|
|
145 |
CAT_AUTH = { |
|
146 |
'production': { |
|
147 |
"CAT_API_KEY": "<provided API key>", |
|
148 |
"CAT_API_URL": "https://cat.eduroam.org/admin/API.php", |
|
149 |
"CAT_PROFILES_URL": "https://cat.eduroam.org/", |
|
150 |
"CAT_FEDMGMT_URL": "https://cat.eduroam.org/admin/overview_federation.php" |
|
151 |
}, |
|
152 |
'testing': { |
|
153 |
"CAT_API_KEY": "<provided API key>", |
|
154 |
"CAT_API_URL": "https://cat-test.eduroam.org/test/admin/API.php", |
|
155 |
"CAT_PROFILES_URL": "https://cat-test.eduroam.org/test", |
|
156 |
"CAT_FEDMGMT_URL": "https://cat-test.eduroam.org/test/admin/overview_federation.php" |
|
157 |
}, |
|
158 |
} |
|
159 |
|
|
160 |
For more information about eduroam CAT, you may read: [A guide to eduroam CAT for federation administrators](https://confluence.terena.org/display/H2eduroam/A+guide+to+eduroam+CAT+for+federation+administrators). |
|
161 |
|
|
162 |
### Extra Apps |
|
163 |
In case one wants to extend some of the settings only for the local instance, they can prepend *EXTRA_* on the attribute they want to extend. For example: |
|
164 |
|
|
165 |
EXTRA_INSTALLED_APPS = ( |
|
166 |
'django_debug_toolbar', |
|
167 |
) |
|
168 |
|
|
169 |
## Database Sync |
|
170 |
Once you are done with local_settings.py run: |
|
171 |
|
|
172 |
./manage.py syncdb |
|
173 |
|
|
174 |
Create a superuser, it comes in handy. And then run south migration to complete:: |
|
175 |
|
|
176 |
./manage.py migrate |
|
177 |
|
|
178 |
Now you should have a clean database with all the tables created. |
|
179 |
|
|
180 |
## Running the server |
|
181 |
|
|
182 |
|
|
183 |
We suggest using Apache and mod_wsgi. Below is an example configuration:: |
|
184 |
|
|
185 |
# Tune wsgi daemon as necessary: processes=x threads=y |
|
186 |
WSGIDaemonProcess djnro display-name=%{GROUP} python-path=/path/to/djnro/ |
|
187 |
|
|
188 |
<VirtualHost *:443> |
|
189 |
ServerName example.com |
|
190 |
|
|
191 |
Alias /static /path/to/djnro/static |
|
192 |
WSGIScriptAlias / /path/to/djnro/djnro/wsgi.py |
|
193 |
<Directory /path/to/djnro/djnro> |
|
194 |
<Files wsgi.py> |
|
195 |
WSGIProcessGroup djnro |
|
196 |
Order deny,allow |
|
197 |
Allow from all |
|
198 |
</Files> |
|
199 |
</Directory> |
|
200 |
|
|
201 |
SSLEngine on |
|
202 |
SSLCertificateFile ... |
|
203 |
SSLCertificateChainFile ... |
|
204 |
SSLCertificateKeyFile ... |
|
205 |
|
|
206 |
# Shibboleth SP configuration |
|
207 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
|
208 |
Alias /shibboleth-sp /usr/share/shibboleth |
|
209 |
|
|
210 |
# SSO through Shibboleth SP: |
|
211 |
<Location /login> |
|
212 |
AuthType shibboleth |
|
213 |
ShibRequireSession On |
|
214 |
ShibUseHeaders On |
|
215 |
require valid-user |
|
216 |
</Location> |
|
217 |
<Location /Shibboleth.sso> |
|
218 |
SetHandler shib |
|
219 |
</Location> |
|
220 |
</VirtualHost> |
|
221 |
|
|
222 |
*Info*: It is strongly recommended to allow access to `/(admin|overview|alt-login)` *ONLY* from trusted subnets. |
|
223 |
|
|
224 |
Once you are done, restart apache. |
|
225 |
|
|
226 |
## Fetch KML |
|
227 |
A Django management command, named fetch_kml, fetches the KML document and updates the cache with eduroam service locations. It is suggested to periodically run this command in a cron job in order to keep the map up to date:: |
|
228 |
|
|
229 |
./manage.py fetch_kml |
|
230 |
|
|
231 |
## Initial Data |
|
232 |
|
|
233 |
In order to start using DjNRO you need to create a Realm record for your NRO along with one or more contacts linked to it. You can visit the Django admin interface `https://<hostname>/admin` and add a Realm (remember to set REALM_COUNTRIES in local_settings.py). |
|
234 |
In DjNRO the NRO sets the environment for the institution eduroam admins. Therefore the NRO has to insert the initial data for his/her clients/institutions in the *Institutions* Model, again using the Django admin interface. As an alternative, you can copy your existing `institution.xml` to `/path/to/djnro` and run the following to import institution data:: |
|
235 |
|
|
236 |
./manage.py parse_instituion_xml |
|
237 |
|
|
238 |
## Exporting Data |
|
239 |
DjNRO can export data in formats suitable for use by other software. |
|
240 |
|
|
241 |
XML documents conforming to the `eduroam database <https://monitor.eduroam.org/database.php>`_ schemata are exported at the following URLs, as required for harvesting by eduroam.org:: |
|
242 |
|
|
243 |
/general/realm.xml |
|
244 |
/general/institution.xml |
|
245 |
/usage/realm_data.xml |
|
246 |
|
|
247 |
A list of institution administrators can be exported in CSV format or a plain format suitable for use by a mailing list (namely `Sympa <http://www.sympa.org/manual/parameters-data-sources#include_remote_file>`_). This data is available through: |
|
248 |
|
|
249 |
* a management comand `./manage.py contacts`, which defaults to CSV output (currently with headers in Greek!) and can switch to plain output using `--mail-list`. |
|
250 |
|
|
251 |
* a view (`adminlist`), which only supports output in the latter plain text format. |
|
252 |
|
|
253 |
Likewise, data that can be used as input for automatic configuration of `Federation Level RADIUS Servers (FLRS)` can be exported in YAML/JSON format, through: |
|
254 |
|
|
255 |
* a management command (`./manage.py servdata`) |
|
256 |
|
|
257 |
* a view (`sevdata`) |
|
258 |
|
|
259 |
Output format defaults to YAML and can be overriden respectively: |
|
260 |
|
|
261 |
* by using `--output=json` |
|
262 |
|
|
263 |
* by sending an `Accept: application/json` HTTP header |
|
264 |
|
|
265 |
We also provide a sample script for reading this data (`extras/servdata_consumer.py`) along with templates (in the same directory) for producing configuration suitable for FreeRADIUS and radsecproxy. This script requires the following python packages: |
|
266 |
|
|
267 |
* python-requests |
|
268 |
|
|
269 |
* python-yaml |
|
270 |
|
|
271 |
* python-mako (for the templates) |
|
272 |
|
|
273 |
Take the time to read the default settings at the top of the script and run it with `--help`. The templates are based on assumptions that may not match your setup; they are mostly provided as a proof of concept. |
|
274 |
|
|
275 |
*attention* |
|
276 |
**The `adminlist` and `servdata` views are commented out by default in `djnro/urls.py`. Make sure you protect them (SSL, ACL and/or authentication) at the HTTP server before you enable them, as they may expose private/sensitive data.** |
|
277 |
|
|
278 |
## Next Steps (Branding) |
|
279 |
|
|
280 |
The majority of branding is done via the NRO variables in local_settings.py. You might also want to change the logo of the application. Within the static/img/eduroam_branding folder you will find the XCF files logo_holder, logo_small. |
|
281 |
|
|
282 |
## Upgrade Instructions |
|
283 |
|
|
284 |
* Backup your `settings.py` and `local_settings` file and any local modifications. |
|
285 |
|
|
286 |
* Update the code. |
|
287 |
|
|
288 |
* Copy `djnro/local_settings.py.dist` to `djnro/local_settings.py` and modify it to match your previous configuration. |
|
289 |
|
|
290 |
* edit the apache configuration in order to work with the new location of wsgi and set the python-path attribute. |
|
291 |
|
|
292 |
* remove old wsgi file `/path/to/djnro/apache/django.wsgi` and parent directory |
|
293 |
|
|
294 |
* remove django-extensions from `INSTALLED_APPS` |
|
295 |
|
|
296 |
* Add timeout in cache configuration |
|
297 |
|
|
298 |
* Make sure you have installed the following required packages (some of these introduced in 0.9): |
|
299 |
|
|
300 |
* python-oauth2 |
|
301 |
|
|
302 |
* python-requests |
|
303 |
|
|
304 |
* python-lxml |
|
305 |
|
|
306 |
* python-yaml |
|
307 |
|
|
308 |
* run `./manage.py migrate` |
|
309 |
|
|
310 |
*attention* |
|
311 |
|
|
312 |
**You had previously copied `urls.py.dist` to `urls.py`. This is no longer supported; we now use `djnro/urls.py`. URLs that provide sensitive data are disabled (commented out) by default. You may have to edit the file according to your needs.** |
|
313 |
|
|
314 |
## LDAP Authentication |
|
315 |
|
|
316 |
If you want to use LDAP authentication, local_settings.py must be amended:: |
|
317 |
|
|
318 |
EXTRA_AUTHENTICATION_BACKENDS = ( |
|
319 |
..., |
|
320 |
'django_auth_ldap.backend.LDAPBackend', |
|
321 |
..., |
|
322 |
) |
|
323 |
|
|
324 |
# LDAP CONFIG |
|
325 |
import ldap |
|
326 |
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType |
|
327 |
AUTH_LDAP_BIND_DN = "" |
|
328 |
AUTH_LDAP_BIND_PASSWORD = "" |
|
329 |
AUTH_LDAP_SERVER_URI = "ldap://foo.bar.org" |
|
330 |
AUTH_LDAP_START_TLS = True |
|
331 |
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=People, dc=bar, dc=foo", |
|
332 |
ldap.SCOPE_SUBTREE, "(uid=%(user)s)") |
|
333 |
AUTH_LDAP_USER_ATTR_MAP = { |
|
334 |
"first_name":"givenName", |
|
335 |
"last_name": "sn", |
|
336 |
"email": "mail |
|
337 |
} |
|
338 |
# Set up the basic group parameters. |
|
339 |
AUTH_LDAP_GROUP_SEARCH = LDAPSearch( |
|
340 |
"ou=Groups,dc=foo,dc=bar,dc=org",ldap.SCOPE_SUBTREE, objectClass=groupOfNames" |
|
341 |
) |
|
342 |
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType() |
|
343 |
AUTH_LDAP_USER_FLAGS_BY_GROUP = { |
|
344 |
"is_active": "cn=NOC, ou=Groups, dc=foo, dc=bar, dc=org", |
|
345 |
"is_staff": "cn=staff, ou=Groups, dc=foo, dc=bar, dc=org", |
|
346 |
"is_superuser": "cn=NOC, ou=Groups,dc=foo, dc=bar, dc=org" |
|
347 |
} |
|
348 |
|
|
349 |
|
|
350 |
## Pebble Watch Application - pebduroam |
|
351 |
|
|
352 |
|
|
353 |
The closest point API allows for development of location aware-applications. |
|
354 |
Pebduroam is a Pebble watch application that fetches the closest eduroam access point plus walking instructions on how to reach it. |
|
355 |
Installing the application on your Pebble watch can be done in 2 ways: |
|
356 |
|
|
357 |
* You can install the application via the Pebble App Store: `pebduroam <https://apps.getpebble.com/applications/5384b2119c84af48350000c7>`_ |
|
358 |
|
|
359 |
* You can install the application and contribute to its development via github: `pebduroam github repo <https://github.com/leopoul/pebduroam>`_. |
|
360 |
|
|
361 |
* You need to have a Cloudpebble account to accomplish this. |
|
362 |
|
|
363 |
* Once logged-in you need to select Import - Import from github and paste the pebduroam github repo url in the corresponding text box. |
|
364 |
|
|
365 |
* Having configured your Pebble watch in developer mode will allow you to build and install your cloned project source directly on your watch. |
|
366 |
|
|
367 |
**attention** |
|
368 |
Currently pebduroam uses GRNET's djnro closest point API. To switch the Pebble app to your djnro installation you need to follow the second method of installation |
|
369 |
|
b/docs/installation/requirements.md | ||
---|---|---|
1 |
# Required Packages |
|
2 |
|
|
3 |
## Dependencies |
|
4 |
|
|
5 |
DjNRO heavily depends on the following: |
|
6 |
|
|
7 |
* Python (<3 & >=2.6) |
|
8 |
* memcached |
|
9 |
* A mail server - Tested with exim |
|
10 |
* python packages located in requirements.txt, you can install them with `pip install -r requirements.txt` |
|
11 |
|
|
12 |
## Conditional Dependencies |
|
13 |
* python-pip |
|
14 |
* python-mysqldb (If you wish to use MySQL as the DB backend) |
|
15 |
* mysql-client |
|
16 |
* apache2 (We suggest apache with mod_rewrite enabled - use your preferred server in case you dont want to use shibboleth) |
|
17 |
* gettext: only if one will be editing and compiling translations |
|
18 |
* python-django-auth-ldap: if ldap authentication backend will be used. |
|
19 |
|
|
20 |
## Django Social Auth |
|
21 |
User authentication via social media is carried out by the [python-social-auth](http://http://django-social-auth.readthedocs.org/en/latest/index.html) python-social-auth package. |
|
22 |
|
|
23 |
|
|
24 |
## Pip requirements.txt file |
|
25 |
DjNRO has also a requirements file which can be used with pip |
/dev/null | ||
---|---|---|
1 |
# -*- coding: utf-8 -*- |
|
2 |
# |
|
3 |
# DjNRO (eduroam) documentation build configuration file |
|
4 |
# |
|
5 |
# This file is execfile()d with the current directory set to its containing dir. |
|
6 |
# |
|
7 |
# Note that not all possible configuration values are present in this |
|
8 |
# autogenerated file. |
|
9 |
# |
|
10 |
# All configuration values have a default; values that are commented out |
|
11 |
# serve to show the default. |
|
12 |
|
|
13 |
import sys, os |
|
14 |
|
|
15 |
|
|
16 |
# Optional. Use a shorter name to conserve nav. bar space. |
|
17 |
|
|
18 |
# If extensions (or modules to document with autodoc) are in another directory, |
|
19 |
# add these directories to sys.path here. If the directory is relative to the |
|
20 |
# documentation root, use os.path.abspath to make it absolute, like shown here. |
|
21 |
|
|
22 |
|
|
23 |
# -- General configuration ----------------------------------------------------- |
|
24 |
|
|
25 |
# If your documentation needs a minimal Sphinx version, state it here. |
|
26 |
#needs_sphinx = "1.0" |
|
27 |
|
|
28 |
# Add any Sphinx extension module names here, as strings. They can be extensions |
|
29 |
# coming with Sphinx (named "sphinx.ext.*") or your custom ones. |
|
30 |
extensions = [ |
|
31 |
"sphinx.ext.todo", |
|
32 |
"sphinx.ext.graphviz", |
|
33 |
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.autosummary' |
|
34 |
] |
|
35 |
|
|
36 |
# Add any paths that contain templates here, relative to this directory. |
|
37 |
#templates_path = ["_templates"] |
|
38 |
|
|
39 |
# The suffix of source filenames. |
|
40 |
source_suffix = ".rst" |
|
41 |
|
|
42 |
# The encoding of source files. |
|
43 |
source_encoding = "utf-8" |
|
44 |
|
|
45 |
# The master toctree document. |
|
46 |
master_doc = "index" |
|
47 |
|
|
48 |
# General information about the project. |
|
49 |
project = u"DjNRO" |
|
50 |
copyright = u"2014, GRNET S.A. - Designed and developed by Leonidas Poulopoulos, Zenon Mousmoulas and Stavros Kroustouris - GRNET NOC" |
|
51 |
|
|
52 |
# The version info for the project you're documenting, acts as replacement for |
|
53 |
# |version| and |release|, also used in various other places throughout the |
|
54 |
# built documents. |
|
55 |
# |
|
56 |
# These next two will be passed via the command line, see the makefile |
|
57 |
# The short X.Y version |
|
58 |
version = "0.9" |
|
59 |
# The full version, including alpha/beta/rc tags. |
|
60 |
release = "0.9.1" |
|
61 |
|
|
62 |
# The language for content autogenerated by Sphinx. Refer to documentation |
|
63 |
# for a list of supported languages. |
|
64 |
language = "en" |
|
65 |
|
|
66 |
# There are two options for replacing |today|: either, you set today to some |
|
67 |
# non-false value, then it is used: |
|
68 |
#today = "" |
|
69 |
# Else, today_fmt is used as the format for a strftime call. |
|
70 |
#today_fmt = "%B %d, %Y" |
|
71 |
|
|
72 |
# List of documents that shouldn't be included in the build. |
|
73 |
#unused_docs = [] |
|
74 |
|
|
75 |
# List of directories, relative to source directory, that shouldn't be searched |
|
76 |
# for source files. |
|
77 |
#exclude_trees = [ |
|
78 |
# "_build", |
|
79 |
# "api", |
|
80 |
# ] |
|
81 |
|
|
82 |
# The reST default role (used for this markup: `text`) to use for all documents. |
|
83 |
#default_role = None |
|
84 |
|
|
85 |
# If true, "()" will be appended to :func: etc. cross-reference text. |
|
86 |
#add_function_parentheses = True |
|
87 |
|
|
88 |
# If true, the current module name will be prepended to all description |
|
89 |
# unit titles (such as .. function::). |
|
90 |
#add_module_names = True |
|
91 |
|
|
92 |
# If true, sectionauthor and moduleauthor directives will be shown in the |
|
93 |
# output. They are ignored by default. |
|
94 |
#show_authors = False |
|
95 |
|
|
96 |
# The name of the Pygments (syntax highlighting) style to use. |
|
97 |
pygments_style = "sphinx" |
|
98 |
|
|
99 |
# A list of ignored prefixes for module index sorting. |
|
100 |
#modindex_common_prefix = ['iooclient.'] |
|
101 |
|
|
102 |
|
|
103 |
# -- Options for HTML output --------------------------------------------------- |
|
104 |
|
|
105 |
# The theme to use for HTML and HTML Help pages. See the documentation for |
|
106 |
# a list of builtin themes. |
|
107 |
#html_theme = "sphinxdoc" |
|
108 |
|
|
109 |
# Theme options are theme-specific and customize the look and feel of a theme |
|
110 |
# further. For a list of options available for each theme, see the |
|
111 |
# documentation. |
|
112 |
#html_theme_options = {} |
|
113 |
|
|
114 |
# Add any paths that contain custom themes here, relative to this directory. |
|
115 |
#html_theme_path = [] |
|
116 |
|
|
117 |
# The name for this set of Sphinx documents. If None, it defaults to |
|
118 |
# "<project> v<release> documentation". |
|
119 |
#html_title = None |
|
120 |
|
|
121 |
# A shorter title for the navigation bar. Default is the same as html_title. |
|
122 |
#html_short_title = None |
|
123 |
|
|
124 |
# The name of an image file (relative to this directory) to place at the top |
|
125 |
# of the sidebar. |
|
126 |
html_logo = "logo.png" |
|
127 |
|
|
128 |
# The name of an image file (within the static path) to use as favicon of the |
|
129 |
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
|
130 |
# pixels large. |
|
131 |
#html_favicon = None |
|
132 |
|
|
133 |
# Add any paths that contain custom static files (such as style sheets) here, |
|
134 |
# relative to this directory. They are copied after the builtin static files, |
|
135 |
# so a file named "default.css" will overwrite the builtin "default.css". |
|
136 |
html_static_path = ['_static'] |
|
137 |
|
|
138 |
# If not "", a "Last updated on:" timestamp is inserted at every page bottom, |
|
139 |
# using the given strftime format. |
|
140 |
#html_last_updated_fmt = "%b %d, %Y" |
|
141 |
|
|
142 |
# If true, SmartyPants will be used to convert quotes and dashes to |
|
143 |
# typographically correct entities. |
|
144 |
#html_use_smartypants = True |
|
145 |
|
|
146 |
# Custom sidebar templates, maps document names to template names. |
|
147 |
#html_sidebars = {} |
|
148 |
|
|
149 |
# Additional templates that should be rendered to pages, maps page names to |
|
150 |
# template names. |
|
151 |
#html_additional_pages = {} |
|
152 |
|
|
153 |
# If false, no module index is generated. |
|
154 |
html_use_modindex = False |
|
155 |
|
|
156 |
# If false, no index is generated. |
|
157 |
html_use_index = False |
|
158 |
|
|
159 |
# If true, the index is split into individual pages for each letter. |
|
160 |
#html_split_index = False |
|
161 |
|
|
162 |
# If true, links to the reST sources are added to the pages. |
|
163 |
#html_show_sourcelink = True |
|
164 |
|
|
165 |
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. |
|
166 |
#html_show_sphinx = True |
|
167 |
|
|
168 |
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. |
|
169 |
#html_show_copyright = True |
|
170 |
|
|
171 |
# If true, an OpenSearch description file will be output, and all pages will |
|
172 |
# contain a <link> tag referring to it. The value of this option must be the |
|
173 |
# base URL from which the finished HTML is served. |
|
174 |
#html_use_opensearch = "" |
|
175 |
|
|
176 |
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
|
177 |
#html_file_suffix = "" |
|
178 |
|
|
179 |
# Output file base name for HTML help builder. |
|
180 |
htmlhelp_basename = "eduroamdoc" |
|
181 |
|
|
182 |
intersphinx_mapping = {'http://docs.python.org/': None} |
|
183 |
|
|
184 |
autoclass_content = 'both' |
/dev/null | ||
---|---|---|
1 |
DjNRO: Django National Roaming Operator or how to manage your eduroam database |
|
2 |
============================================================================== |
|
3 |
|
|
4 |
DjNRO = Django + NRO |
|
5 |
|
|
6 |
About |
|
7 |
----- |
|
8 |
In the `eduroam <http://www.eduroam.org>`_ world, NRO stands for National Roaming Operator. |
|
9 |
Maintaining and managing a local eduroam database is quite an important responsibility of an eduroam NRO. |
|
10 |
eduroam.org periodically polls and gathers information from all participating domains. |
|
11 |
Information is provided upstream, in a structured way (XML format) and consists of participating institutions' data, location data along with monitoring data - though provisioning of monitoring data has been superseeded by the f-Ticks mechanism. |
|
12 |
|
|
13 |
The source of information should be the local eduroam database. So, changes to the database should be reflected to the XML files. |
|
14 |
New eduroam locations, changes in contacts and information about each location should be up-to-date so as to ease the eduroam usage and assist eduroam users whenever they need support. |
|
15 |
|
|
16 |
DjNRO is a Django platform that eases the management process of a National Roaming Operator. DjNRO complies with the `eduroam database <http://monitor.eduroam.org/database.php>`_ and the eduroam XSDs. |
|
17 |
Thus, apart from domain management, it can generate the necessary xml files for eduroam.org monitoring. |
|
18 |
|
|
19 |
DjNRO is more than keeping eduroam.org updated with data. |
|
20 |
|
|
21 |
In essence it is a distributed management application. It is distributed in the sense that information about each institution locations and services is kept up-to-date by each local eduroam administrator. Keeping in pace with eduroam's federated nature, our implementation uses federated authentication/authorisation mechanisms, namely Shibboleth. |
|
22 |
In case Shibboleth is not an option for an institution, a social media auth mechanism comes in handy. The local institution eduroam administrators can become DjNRO admins. Local eduroam administrators register to the platform via Shibboleth or social media auth. The NRO's responsibility is to activate their accounts. |
|
23 |
|
|
24 |
From then on they can manage their eduroam locations, contact points and institution information. The administrative interface especially the locations management part, is heavily implemented with Google Maps. This makes editing easier, faster and accurate. |
|
25 |
|
|
26 |
Installation and customization is fairly easy and is described in the following sections. |
|
27 |
|
|
28 |
.. attention:: |
|
29 |
Installation instructions assume a clean Debian Wheezy with Django 1.4 |
|
30 |
|
|
31 |
Currently the source code is availiable at code.grnet.gr and github and can be cloned via git:: |
|
32 |
|
|
33 |
git clone https://code.grnet.gr/git/djnro |
|
34 |
git clone https://github.com/grnet/djnro.git |
|
35 |
|
|
36 |
The Greek eduroam webpage is a living example of DjNRO: `eduroam|gr <http://www.eduroam.gr>`_ |
|
37 |
|
|
38 |
Features |
|
39 |
-------- |
|
40 |
|
|
41 |
* Allow your local eduroam admins to edit their local eduroam data (AP locations, server params, etc) |
|
42 |
* Visualize the information via Google Maps |
|
43 |
* Eduroam world maps overview via daily update on eduroam.org KML file |
|
44 |
* Find your closest eduroam in the world |
|
45 |
* **New** Allow for eduroam CAT institution enrollments |
|
46 |
* **New** Extract contact info for mailing list creation |
|
47 |
* **New** Server monitoring data |
|
48 |
* **New** Pebble watch app with closest eduroam walking instrunctions |
|
49 |
|
|
50 |
Bootstrap CSS framework with responsive design makes it work on every device |
|
51 |
|
|
52 |
Requirements |
|
53 |
------------ |
|
54 |
|
|
55 |
.. toctree:: |
|
56 |
|
|
57 |
require |
|
58 |
|
|
59 |
Installation |
|
60 |
------------ |
|
61 |
|
|
62 |
.. toctree:: |
|
63 |
|
|
64 |
install |
/dev/null | ||
---|---|---|
1 |
.. _install-label: |
|
2 |
|
|
3 |
Installation/Configuration |
|
4 |
========================== |
|
5 |
.. contents:: |
|
6 |
|
|
7 |
.. note:: |
|
8 |
Installation instructions assume a clean Debian Wheezy with Django 1.4 |
|
9 |
|
|
10 |
Assuming that you have installed all the requirements described in :ref:`require-label` you can install the DjNRO project. |
|
11 |
|
|
12 |
The software is published at code.grnet.gr and can be downloaded using git:: |
|
13 |
|
|
14 |
git clone https://code.grnet.gr/git/djnro |
|
15 |
|
|
16 |
It is also available on GitHub:: |
|
17 |
|
|
18 |
https://github.com/grnet/djnro/ |
|
19 |
|
|
20 |
|
|
21 |
Project & Local Settings |
|
22 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
|
23 |
|
|
24 |
.. attention:: |
|
25 |
In version 0.9 settings were split in two parts: settings.py and local_settings.py |
|
26 |
|
|
27 |
The file settings.py contains settings distributed by the project, which should normally not be necessary to modify. Options specific to the particular installation must be configured in local_settings.py. This file must be created by copying local_settings.py.dist:: |
|
28 |
|
|
29 |
cd djnro |
|
30 |
cp djnro/local_settings.py.dist djnro/local_settings.py |
|
31 |
|
|
32 |
|
|
33 |
|
|
34 |
The following variables/settings need to be altered or set: |
|
35 |
|
|
36 |
Set Admin contacts:: |
|
37 |
|
|
38 |
ADMINS = ( |
|
39 |
('Admin', 'admin@example.com'), |
|
40 |
) |
|
41 |
|
|
42 |
Set the database connection params:: |
|
43 |
|
|
44 |
DATABASES = { |
|
45 |
... |
|
46 |
} |
|
47 |
|
|
48 |
For a production instance and once DEBUG is set to False set the ALLOWED_HOSTS:: |
|
49 |
|
|
50 |
ALLOWED_HOSTS = ['.example.com'] |
|
51 |
|
|
52 |
Set your timezone and Languages:: |
|
53 |
|
|
54 |
TIME_ZONE = 'Europe/Athens' |
|
55 |
|
|
56 |
LANGUAGES = ( |
|
57 |
('el', _('Greek')), |
|
58 |
('en', _('English')), |
|
59 |
) |
|
60 |
|
|
61 |
Set your static root and url:: |
|
62 |
|
|
63 |
STATIC_ROOT = '/path/to/static' |
|
64 |
STATIC_URL = 'http://www.example.com/static' |
|
65 |
|
|
66 |
.. _Django: https://docs.djangoproject.com/en/1.4/howto/static-files/#serving-static-files-in-development |
|
67 |
.. attention:: |
|
68 |
The STATIC_URL setting works only if DEBUG=False. For more see the Django_ docs. |
|
69 |
|
|
70 |
|
|
71 |
|
|
72 |
Set the secret key:: |
|
73 |
|
|
74 |
SECRET_KEY = '<put something really random here, eg. %$#%@#$^2312351345#$%3452345@#$%@#$234#@$hhzdavfsdcFDGVFSDGhn>' |
|
75 |
|
|
76 |
Django social auth needs changes in the Authentication Backends depending on which social auth you want to enable:: |
|
77 |
|
|
78 |
AUTHENTICATION_BACKENDS = ( |
|
79 |
'djnro.djangobackends.shibauthBackend.shibauthBackend', |
|
80 |
... |
|
81 |
'django.contrib.auth.backends.ModelBackend', |
|
82 |
) |
|
83 |
|
|
84 |
Set your template dirs:: |
|
85 |
|
|
86 |
TEMPLATE_DIRS = ( |
|
87 |
"/example/templates", |
|
88 |
) |
|
89 |
|
|
90 |
As the application includes a "Nearest eduroam" functionality, global eduroam service locations are harvested from the KML file published at eduroam.org:: |
|
91 |
|
|
92 |
EDUROAM_KML_URL = 'http://monitor.eduroam.org/kml/all.kml' |
|
93 |
|
|
94 |
|
|
95 |
Depending on your AAI policy set an appropriate authEntitlement:: |
|
96 |
|
|
97 |
SHIB_AUTH_ENTITLEMENT = 'urn:mace:example.com:pki:user' |
|
98 |
|
|
99 |
Mail server parameters:: |
|
100 |
|
|
101 |
SERVER_EMAIL = "Example domain eduroam Service <noreply@example.com>" |
|
102 |
EMAIL_SUBJECT_PREFIX = "[eduroam] " |
|
103 |
|
|
104 |
NRO contact mails:: |
|
105 |
|
|
106 |
NOTIFY_ADMIN_MAILS = ["mail1@example.com", "mail2@example.com"] |
|
107 |
|
|
108 |
Set your cache backend (if you want to use one). For production instances you can go with memcached. For development you can keep the provided dummy instance:: |
|
109 |
|
|
110 |
|
|
111 |
CACHES = { |
|
112 |
'default': { |
|
113 |
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', |
|
114 |
'LOCATION': '127.0.0.1:11211', |
|
115 |
} |
|
116 |
} |
|
117 |
|
|
118 |
Models Name_i18n and URL_i18n include a language choice field |
|
119 |
If languages are the same with LANGUAGES variable, simply do URL_NAME_LANGS = LANGUAGES else set your own:: |
|
120 |
|
|
121 |
URL_NAME_LANGS = ( |
|
122 |
('en', 'English' ), |
|
123 |
('el', 'Ελληνικά'), |
|
124 |
) |
|
125 |
|
|
126 |
NRO specific parameters. These affect HTML templates:: |
|
127 |
|
|
128 |
# Frontend country specific vars, eg. Greece |
|
129 |
NRO_COUNTRY_NAME = _('My Country') |
|
130 |
# Variable used by context_processor to display the "eduroam | <country_code>" in base.html |
|
131 |
NRO_COUNTRY_CODE = 'gr' |
|
132 |
# main domain url used in right top icon, eg. http://www.grnet.gr |
|
133 |
NRO_DOMAIN_MAIN_URL = "http://www.example.com" |
|
134 |
# provider info for footer |
|
135 |
NRO_PROV_BY_DICT = {"name": "EXAMPLE DEV TEAM", "url": "http://devteam.example.com"} |
|
136 |
#NRO social media contact (Use: // to preserve https) |
|
137 |
NRO_PROV_SOCIAL_MEDIA_CONTACT = [ |
|
138 |
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME1(eg. Facebook)"}, |
|
139 |
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME2(eg. Twitter)"}, |
|
140 |
] |
|
141 |
# map center (lat, lng) |
|
142 |
MAP_CENTER = (36.97, 23.71) |
|
143 |
#Helpdesk, used in base.html: |
|
144 |
NRO_DOMAIN_HELPDESK_DICT = {"name": _("Domain Helpdesk"), 'email':'helpdesk@example.com', 'phone': '12324567890', 'uri': 'helpdesk.example.com'} |
|
145 |
|
|
146 |
Set the Realm country for REALM model:: |
|
147 |
|
|
148 |
#Countries for Realm model: |
|
149 |
REALM_COUNTRIES = ( |
|
150 |
('country_2letters', 'Country' ), |
|
151 |
) |
|
152 |
|
|
153 |
Attribute map to match your AAI policy and SSO software (typically Shibboleth SP):: |
|
154 |
|
|
155 |
#Shibboleth attribute map |
|
156 |
SHIB_USERNAME = ['HTTP_EPPN'] |
|
157 |
SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL'] |
|
158 |
SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME'] |
|
159 |
SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME'] |
|
160 |
SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT'] |
|
161 |
|
|
162 |
Django Social Auth parameters:: |
|
163 |
|
|
164 |
SOCIAL_AUTH_TWITTER_KEY = '' |
|
165 |
SOCIAL_AUTH_TWITTER_SECRET = '' |
|
166 |
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = '' |
|
167 |
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ' ' |
|
168 |
SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = [] |
|
169 |
|
|
170 |
|
|
171 |
.. versionadded:: 0.9 |
|
172 |
|
|
173 |
DjNRO provides limited integration with eduroam CAT (Configuration Assistant Tool). Institution administrators can automatically provision their institution to CAT without the intervention of the federation (NRO) administrator. |
|
174 |
|
|
175 |
In order to enable this functionality, you must list at least one instance and the corresponding description in CAT_INSTANCES. Beware that pages accessible by end users currently only show CAT information |
|
176 |
for the instance named `production`. |
|
177 |
|
|
178 |
You must also set the following parameters for each CAT instance in CAT_AUTH: |
|
179 |
|
|
180 |
* CAT_API_KEY: API key for authentication to CAT |
|
181 |
|
|
182 |
* CAT_API_URL: API endpoint URL |
|
183 |
|
|
184 |
* CAT_PROFILES_URL: Base URL for Intitution Download Area pages |
|
185 |
|
|
186 |
* CAT_FEDMGMT_URL: URL For Federation Overview page (currently not in use) |
|
187 |
|
|
188 |
:: |
|
189 |
|
|
190 |
CAT_INSTANCES = ( |
|
191 |
('production', 'cat.eduroam.org'), |
|
192 |
('testing', 'cat-test.eduroam.org'), |
|
193 |
) |
|
194 |
|
|
195 |
CAT_AUTH = { |
|
196 |
'production': { |
|
197 |
"CAT_API_KEY": "<provided API key>", |
|
198 |
"CAT_API_URL": "https://cat.eduroam.org/admin/API.php", |
|
199 |
"CAT_PROFILES_URL": "https://cat.eduroam.org/", |
|
200 |
"CAT_FEDMGMT_URL": "https://cat.eduroam.org/admin/overview_federation.php" |
|
201 |
}, |
|
202 |
'testing': { |
|
203 |
"CAT_API_KEY": "<provided API key>", |
|
204 |
"CAT_API_URL": "https://cat-test.eduroam.org/test/admin/API.php", |
|
205 |
"CAT_PROFILES_URL": "https://cat-test.eduroam.org/test", |
|
206 |
"CAT_FEDMGMT_URL": "https://cat-test.eduroam.org/test/admin/overview_federation.php" |
|
207 |
}, |
|
208 |
} |
|
209 |
|
|
210 |
For more information about eduroam CAT, you may read: `A guide to eduroam CAT for federation administrators <https://confluence.terena.org/display/H2eduroam/A+guide+to+eduroam+CAT+for+federation+administrators>`_. |
|
211 |
|
|
212 |
In case one wants to extend some of the settings only for the local instance, they can prepend *EXTRA_* on the attribute they want to extend. For example:: |
|
213 |
|
|
214 |
EXTRA_INSTALLED_APPS = ( |
|
215 |
'django_debug_toolbar', |
|
216 |
) |
|
217 |
|
|
218 |
Database Sync |
|
219 |
^^^^^^^^^^^^^ |
|
220 |
|
|
221 |
Once you are done with local_settings.py run:: |
|
222 |
|
|
223 |
./manage.py syncdb |
|
224 |
|
|
225 |
Create a superuser, it comes in handy. And then run south migration to complete:: |
|
226 |
|
|
227 |
./manage.py migrate |
|
228 |
|
|
229 |
Now you should have a clean database with all the tables created. |
|
230 |
|
|
231 |
Running the server |
|
232 |
^^^^^^^^^^^^^^^^^^ |
|
233 |
|
|
234 |
We suggest using Apache and mod_wsgi. Below is an example configuration:: |
|
235 |
|
|
236 |
# Tune wsgi daemon as necessary: processes=x threads=y |
|
237 |
WSGIDaemonProcess djnro display-name=%{GROUP} python-path=/path/to/djnro/ |
|
238 |
|
|
239 |
<VirtualHost *:443> |
|
240 |
ServerName example.com |
|
241 |
|
|
242 |
Alias /static /path/to/djnro/static |
|
243 |
WSGIScriptAlias / /path/to/djnro/djnro/wsgi.py |
|
244 |
<Directory /path/to/djnro/djnro> |
|
245 |
<Files wsgi.py> |
|
246 |
WSGIProcessGroup djnro |
|
247 |
Order deny,allow |
|
248 |
Allow from all |
|
249 |
</Files> |
|
250 |
</Directory> |
|
251 |
|
|
252 |
SSLEngine on |
|
253 |
SSLCertificateFile ... |
|
254 |
SSLCertificateChainFile ... |
|
255 |
SSLCertificateKeyFile ... |
|
256 |
|
|
257 |
# Shibboleth SP configuration |
|
258 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
|
259 |
Alias /shibboleth-sp /usr/share/shibboleth |
|
260 |
|
|
261 |
# SSO through Shibboleth SP: |
|
262 |
<Location /login> |
|
263 |
AuthType shibboleth |
|
264 |
ShibRequireSession On |
|
265 |
ShibUseHeaders On |
|
266 |
require valid-user |
|
267 |
</Location> |
|
268 |
<Location /Shibboleth.sso> |
|
269 |
SetHandler shib |
|
270 |
</Location> |
|
271 |
</VirtualHost> |
|
272 |
|
|
273 |
*Info*: It is strongly recommended to allow access to ``/(admin|overview|alt-login)`` *ONLY* from trusted subnets. |
|
274 |
|
|
275 |
Once you are done, restart apache. |
|
276 |
|
|
277 |
Fetch KML |
|
278 |
^^^^^^^^^ |
|
279 |
A Django management command, named fetch_kml, fetches the KML document and updates the cache with eduroam service locations. It is suggested to periodically run this command in a cron job in order to keep the map up to date:: |
|
280 |
|
|
281 |
./manage.py fetch_kml |
|
282 |
|
|
283 |
Initial Data |
|
284 |
^^^^^^^^^^^^ |
|
285 |
In order to start using DjNRO you need to create a Realm record for your NRO along with one or more contacts linked to it. You can visit the Django admin interface (``https://<hostname>/admin``) and add a Realm (remember to set REALM_COUNTRIES in local_settings.py). |
|
286 |
In DjNRO the NRO sets the environment for the institution eduroam admins. Therefore the NRO has to insert the initial data for his/her clients/institutions in the *Institutions* Model, again using the Django admin interface. As an alternative, you can copy your existing ``institution.xml`` to ``/path/to/djnro`` and run the following to import institution data:: |
|
287 |
|
|
288 |
./manage.py parse_instituion_xml |
|
289 |
|
|
290 |
Exporting Data |
|
291 |
^^^^^^^^^^^^^^ |
|
292 |
|
|
293 |
DjNRO can export data in formats suitable for use by other software. |
|
294 |
|
|
295 |
XML documents conforming to the `eduroam database <https://monitor.eduroam.org/database.php>`_ schemata are exported at the following URLs, as required for harvesting by eduroam.org:: |
|
296 |
|
|
297 |
/general/realm.xml |
|
298 |
/general/institution.xml |
|
299 |
/usage/realm_data.xml |
|
300 |
|
|
301 |
.. versionadded:: 0.9 |
|
302 |
|
|
303 |
A list of institution administrators can be exported in CSV format or a plain format suitable for use by a mailing list (namely `Sympa <http://www.sympa.org/manual/parameters-data-sources#include_remote_file>`_). This data is available through: |
|
304 |
|
|
305 |
* a management comand (``./manage.py contacts``), which defaults to CSV output (currently with headers in Greek!) and can switch to plain output using ``--mail-list``. |
|
306 |
|
|
307 |
* a view (``adminlist``), which only supports output in the latter plain text format. |
|
308 |
|
|
309 |
Likewise, data that can be used as input for automatic configuration of `Federation Level RADIUS Servers (FLRS)` can be exported in YAML/JSON format, through: |
|
310 |
|
|
311 |
* a management command (``./manage.py servdata``) |
|
312 |
|
|
313 |
* a view (``sevdata``) |
|
314 |
|
|
315 |
Output format defaults to YAML and can be overriden respectively: |
|
316 |
|
|
317 |
* by using ``--output=json`` |
|
318 |
|
|
319 |
* by sending an ``Accept: application/json`` HTTP header |
|
320 |
|
|
321 |
We also provide a sample script for reading this data (``extras/servdata_consumer.py``) along with templates (in the same directory) for producing configuration suitable for FreeRADIUS and radsecproxy. This script requires the following python packages: |
|
322 |
|
|
323 |
* python-requests |
|
324 |
|
|
325 |
* python-yaml |
|
326 |
|
|
327 |
* python-mako (for the templates) |
|
328 |
|
|
329 |
Take the time to read the default settings at the top of the script and run it with ``--help``. The templates are based on assumptions that may not match your setup; they are mostly provided as a proof of concept. |
|
330 |
|
|
331 |
.. attention:: |
|
332 |
The ``adminlist`` and ``servdata`` views are commented out by default in ``djnro/urls.py``. Make sure you protect them (SSL, ACL and/or authentication) at the HTTP server before you enable them, as they may expose private/sensitive data. |
|
333 |
|
|
334 |
Next Steps (Set your Logo) |
|
335 |
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
336 |
The majority of branding is done via the NRO variables in local_settings.py. You might also want to change the logo of the application. Within the static/img/eduroam_branding folder you will find the XCF files logo_holder, logo_small. Edit with Gimp according to your needs and export to logo_holder.png and logo_small.png at the same path. To change the domain logo on top right, replace the static/img/right_logo_small.png file with your own logo (86x40). |
|
337 |
|
|
338 |
Upgrade Instructions |
|
339 |
^^^^^^^^^^^^^^^^^^^^ |
|
340 |
* Backup your ``settings.py`` file and any local modifications. |
|
341 |
|
|
342 |
* Update the code. |
|
343 |
|
|
344 |
* Copy ``djnro/local_settings.py.dist`` to ``djnro/local_settings.py`` and modify it to match your previous configuration. |
|
345 |
|
|
346 |
* edit the apache configuration in order to work with the new location of wsgi and set the python-path attribute. |
|
347 |
|
|
348 |
* remove old wsgi file ``/path/to/djnro/apache/django.wsgi`` and parent directory |
|
349 |
|
|
350 |
* remove django-extensions from `INSTALLED_APPS` |
|
351 |
|
|
352 |
* Add timeout in cache configuration |
|
353 |
|
|
354 |
* Make sure you have installed the following required packages (some of these introduced in 0.9): |
|
355 |
|
|
356 |
* python-oauth2 |
|
357 |
|
|
358 |
* python-requests |
|
359 |
|
|
360 |
* python-lxml |
|
361 |
|
|
362 |
* python-yaml |
|
363 |
|
|
364 |
* run ``./manage.py migrate`` |
|
365 |
|
|
366 |
.. attention:: |
|
367 |
You had previously copied ``urls.py.dist`` to ``urls.py``. This is no longer supported; we now use ``djnro/urls.py``. URLs that provide sensitive data are disabled (commented out) by default. You may have to edit the file according to your needs. |
|
368 |
|
|
369 |
Pip Support |
|
370 |
^^^^^^^^^^^ |
|
371 |
We have added a requirements.txt file, tested for django 1.4.5. You can use it |
|
372 |
with ``pip install -r requirements.txt``. |
|
373 |
|
|
374 |
|
|
375 |
LDAP Authentication |
|
376 |
^^^^^^^^^^^^^^^^^^^ |
|
377 |
If you want to use LDAP authentication, local_settings.py must be amended:: |
|
378 |
|
|
379 |
EXTRA_AUTHENTICATION_BACKENDS = ( |
|
380 |
..., |
|
381 |
'django_auth_ldap.backend.LDAPBackend', |
|
382 |
..., |
|
383 |
) |
|
384 |
|
|
385 |
# LDAP CONFIG |
|
386 |
import ldap |
|
387 |
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType |
|
388 |
AUTH_LDAP_BIND_DN = "" |
|
389 |
AUTH_LDAP_BIND_PASSWORD = "" |
|
390 |
AUTH_LDAP_SERVER_URI = "ldap://foo.bar.org" |
|
391 |
AUTH_LDAP_START_TLS = True |
|
392 |
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=People, dc=bar, dc=foo", |
|
393 |
ldap.SCOPE_SUBTREE, "(uid=%(user)s)") |
|
394 |
AUTH_LDAP_USER_ATTR_MAP = { |
|
395 |
"first_name":"givenName", |
|
396 |
"last_name": "sn", |
|
397 |
"email": "mail |
|
398 |
} |
|
399 |
# Set up the basic group parameters. |
|
400 |
AUTH_LDAP_GROUP_SEARCH = LDAPSearch( |
|
401 |
"ou=Groups,dc=foo,dc=bar,dc=org",ldap.SCOPE_SUBTREE, objectClass=groupOfNames" |
|
402 |
) |
|
403 |
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType() |
|
404 |
AUTH_LDAP_USER_FLAGS_BY_GROUP = { |
|
405 |
"is_active": "cn=NOC, ou=Groups, dc=foo, dc=bar, dc=org", |
|
406 |
"is_staff": "cn=staff, ou=Groups, dc=foo, dc=bar, dc=org", |
|
407 |
"is_superuser": "cn=NOC, ou=Groups,dc=foo, dc=bar, dc=org" |
|
408 |
} |
|
409 |
|
|
410 |
|
|
411 |
Pebble Watch Application - pebduroam |
|
412 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
413 |
|
|
414 |
The closest point API allows for development of location aware-applications. |
|
415 |
Pebduroam is a Pebble watch application that fetches the closest eduroam access point plus walking instructions on how to reach it. |
|
416 |
Installing the application on your Pebble watch can be done in 2 ways: |
|
417 |
|
|
418 |
* You can install the application via the Pebble App Store: `pebduroam <https://apps.getpebble.com/applications/5384b2119c84af48350000c7>`_ |
|
419 |
|
|
420 |
* You can install the application and contribute to its development via github: `pebduroam github repo <https://github.com/leopoul/pebduroam>`_. |
|
421 |
|
|
422 |
* You need to have a Cloudpebble account to accomplish this. |
|
423 |
|
|
424 |
* Once logged-in you need to select Import - Import from github and paste the pebduroam github repo url in the corresponding text box. |
|
425 |
|
|
426 |
* Having configured your Pebble watch in developer mode will allow you to build and install your cloned project source directly on your watch. |
|
427 |
|
|
428 |
.. attention:: |
|
429 |
Currently pebduroam uses GRNET's djnro closest point API. To switch the Pebble app to your djnro installation you need to follow the second method of installation |
|
430 |
|
/dev/null | ||
---|---|---|
1 |
.. _require-label: |
|
2 |
|
|
3 |
Required Packages |
|
4 |
================= |
|
5 |
|
|
6 |
Dependencies |
|
7 |
^^^^^^^^^^^^ |
|
8 |
DjNRO heavily depends on the following: |
|
9 |
|
|
10 |
* Python (<3 & >=2.6) |
|
11 |
* memcached |
|
12 |
* python-mysqldb (If you wish to use MySQL as the DB backend) |
|
13 |
* mysql-client |
|
14 |
* apache2 (We suggest apache with mod_rewrite enabled - use your preferred server) |
|
15 |
* A mail server - Tested with exim |
|
16 |
* python-pip |
|
17 |
* python packages located in requirements.txt, you can install them with `pip install -r requirements.txt` |
|
18 |
|
|
19 |
Conditional Dependencies |
|
20 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
|
21 |
* gettext: only if one will be editing and compiling translations |
|
22 |
* python-django-auth-ldap: if ldap authentication backend will be used. |
|
23 |
|
|
24 |
Django Social Auth |
|
25 |
------------------ |
|
26 |
User authentication via social media is carried out by the `python-django-social-auth <http://http://django-social-auth.readthedocs.org/en/latest/index.html>`_ python-django-social-auth package. We have included python-django-social-auth 0.7.18 in repository because DjNRO requires WrongBackend from social_auth.exceptions; this does not exist in 0.7.0 which ships with Debian Wheezy. |
|
27 |
|
|
28 |
Django Social Auth: Requirements - Dependencies |
|
29 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
30 |
* OpenId support depends on python-openid |
|
31 |
|
|
32 |
* OAuth support depends on python-oauth2 |
|
33 |
|
b/mkdocs.yml | ||
---|---|---|
1 |
site_name: DjNRO |
|
2 |
repo_url: https://github.com/grnet/djnro/ |
|
3 |
docs_dir: docs |
|
4 |
site_author: Stavros Kroustouris |
|
5 |
theme: readthedocs |
|
6 |
pages: |
|
7 |
- 'Introduction': 'index.md' |
|
8 |
- 'Installation': |
|
9 |
- 'Requirements': 'installation/requirements.md' |
|
10 |
- 'Installing DjNRO': 'installation/install.md' |
|
11 |
# - 'Debian': 'installation/debian_wheezy.md' |
|
12 |
# - 'Red Hat': 'installation/redhat.md' |
|
13 |
# - 'Configuration': 'configuration.md' |
Also available in: Unified diff