README.md 8.08 KB
Newer Older
chirac's avatar
chirac committed
1
# Re2o
chirac's avatar
chirac committed
2

chirac's avatar
chirac committed
3 4
Gnu public license v2.0

chirac's avatar
chirac committed
5
## Avant propos 
chirac's avatar
chirac committed
6

Chirac's avatar
Chirac committed
7 8 9 10 11 12 13 14 15 16 17
Re2o est un logiciel d'administration développé initiallement au rezometz. Il
se veut agnostique au réseau considéré, de manière à être installable en 
quelques clics.

Il utilise le framework django avec python3. Il permet de gérer les adhérents, 
les machines, les factures, les droits d'accès, les switchs et la topologie du 
réseau.
De cette manière, il est possible de pluguer très facilement des services 
dessus, qui accèdent à la base de donnée en passant par django (ex : dhcp), en 
chargeant la liste de toutes les mac-ip, ou la liste des mac-ip autorisées sur 
le réseau (adhérent à jour de cotisation).
chirac's avatar
chirac committed
18

19
# Installation
Chirac's avatar
Chirac committed
20

Chirac's avatar
Chirac committed
21
## Installation des dépendances
chirac's avatar
chirac committed
22

Chirac's avatar
Chirac committed
23 24 25 26 27 28
L'installation comporte 3 partie : le serveur web où se trouve le depot re2o
ainsi que toutes ses dépendances, le serveur bdd (mysql ou pgsql) et le 
serveur ldap. Ces 3 serveurs peuvent en réalité être la même machine, ou séparés
(recommandé en production).
Le serveur web sera nommé serveur A, le serveur bdd serveur B et le serveur ldap
serveur C.
29

Chirac's avatar
Chirac committed
30
### Prérequis sur le serveur A
chirac's avatar
chirac committed
31

Chirac's avatar
Chirac committed
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
Voici la liste des dépendances à installer sur le serveur principal (A).

### Avec apt :

#### Sous debian 9

Paquets obligatoires:
 * python3-django (1.10, stretch)
 * python3-dateutil (stretch)
 * texlive-latex-base (stretch)
 * texlive-fonts-recommended (strech)
 * python3-djangorestframework (stretch)
 * python3-django-reversion (stretch)
 * python3-pip (stretch)

Paquet recommandés:
 * python3-django-extensions (stretch)

root's avatar
root committed
50

Chirac's avatar
Chirac committed
51 52
### Autres dépendances : 

Chirac's avatar
Chirac committed
53 54 55 56 57
Paquets préalables à installer avec apt : 
 * libsasl2-dev (stable)
 * libldap2-dev (stable)
 * libssl-dev (stable)

Chirac's avatar
Chirac committed
58 59
Avec pip3 (pip3 install):
 * django-bootstrap3
root's avatar
root committed
60
 * django-ldapdb
Gabriel Detraz's avatar
Gabriel Detraz committed
61
 * django-macaddress
chirac's avatar
chirac committed
62 63

Moteur de db conseillé (mysql), postgresql fonctionne également.
Chirac's avatar
Chirac committed
64
Pour mysql, il faut installer : 
Gabriel Detraz's avatar
Gabriel Detraz committed
65
 * python3-mysqldb
Chirac's avatar
Chirac committed
66 67 68 69
 * mysql-client

### Prérequis sur le serveur B

Gabriel Detraz's avatar
Gabriel Detraz committed
70 71
Sur le serveur B, installer mysql ou postgresql, dans la version stretch.
 * mysql-server (stretch) ou postgresql (stretch)
Chirac's avatar
Chirac committed
72 73 74

### Prérequis sur le serveur C
Sur le serveur C (ldap), avec apt :
Gabriel Detraz's avatar
Gabriel Detraz committed
75
 * slapd (stretch)
Chirac's avatar
Chirac committed
76

Chirac's avatar
Chirac committed
77
### Installation sur le serveur principal A
Chirac's avatar
Chirac committed
78 79

Cloner le dépot re2o à partir du gitlab, par exemple dans /var/www/re2o.
Chirac's avatar
Chirac committed
80 81 82
Ensuite, il faut créer le fichier settings_local.py dans le sous dossier re2o, 
un settings_local.example.py est présent. Les options sont commentées, et des 
options par défaut existent.
Chirac's avatar
Chirac committed
83

Chirac's avatar
Chirac committed
84 85 86
En particulier, il est nécessaire de générer un login/mdp admin pour le ldap et 
un login/mdp pour l'utilisateur sql (cf ci-dessous), à mettre dans 
settings_local.py
Chirac's avatar
Chirac committed
87

Chirac's avatar
Chirac committed
88
### Installation du serveur mysql/postgresql sur B
Chirac's avatar
Chirac committed
89

Chirac's avatar
Chirac committed
90 91 92 93
Sur le serveur mysql ou postgresl, il est nécessaire de créer une base de 
donnée re2o, ainsi qu'un user re2o et un mot de passe associé. 
Ne pas oublier de faire écouter le serveur mysql ou postgresql avec les acl 
nécessaire pour que A puisse l'utiliser.
Chirac's avatar
Chirac committed
94

Chirac's avatar
Chirac committed
95
#### Mysql
Chirac's avatar
Chirac committed
96
Voici les étapes à éxecuter pour mysql :
Gabriel Detraz's avatar
Gabriel Detraz committed
97
 * CREATE DATABASE re2o collate='utf8_general_ci';
Chirac's avatar
Chirac committed
98 99 100
 * CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
 * GRANT ALL PRIVILEGES ON re2o.* TO 'newuser'@'localhost';
 * FLUSH PRIVILEGES;
chirac's avatar
chirac committed
101

Chirac's avatar
Chirac committed
102 103 104 105 106 107
#### Postgresql
 * CREATE DATABASE re2o ENCODING 'UTF8' LC_COLLATE='fr_FR.UTF-8' 
LC_CTYPE='fr_FR.UTF-8';
 * CREATE USER newuser with password 'password';
 * ALTER DATABASE re2o owner to newuser;

Chirac's avatar
Chirac committed
108 109 110 111 112
Si les serveurs A et B ne sont pas la même machine, il est nécessaire de 
remplacer localhost par l'ip avec laquelle A contacte B dans les commandes 
du dessus.
Une fois ces commandes effectuées, ne pas oublier de vérifier que newuser et 
password sont présents dans settings_local.py
chirac's avatar
chirac committed
113

Chirac's avatar
Chirac committed
114
### Installation du serveur ldap sur le serveur C
115

Chirac's avatar
Chirac committed
116 117
Ceci se fait en plusieurs étapes : 
 * générer un login/mdp administrateur (par example mkpasswd sous debian)
Chirac's avatar
Chirac committed
118 119 120 121 122 123 124 125 126
 * Copier depuis re2o/install_utils (dans le dépot re2o) les fichiers db.ldiff 
et schema.ldiff (normalement sur le serveur A) sur le serveur C 
(par ex dans /tmp)
 * Hasher le mot de passe généré en utilisant la commande slappasswd 
(installée par slapd)
 * Remplacer toutes les sections FILL_IN par le hash dans schema.ldiff et 
db.ldiff
 * Remplacer dans schema.ldiff et db.ldiff 'dc=example,dc=org' par le 
suffixe de l'organisation
Chirac's avatar
Chirac committed
127
 * Arréter slapd
Chirac's avatar
Chirac committed
128 129 130 131 132 133 134 135 136
 * Supprimer les données existantes : '''rm -rf /etc/ldap/slapd.d/*''' et 
'''rm -rf /var/lib/ldap/*'''
 * Injecter le nouveau schéma : 
'''slapadd -n 0 -l schema.ldiff -F /etc/ldap/slapd.d/''' et 
'''slapadd -n 1 -l db.ldiff'''
 * Réparer les permissions (chown -R openldap:openldap /etc/ldap/slapd.d et
chown -R openldap:openldap /var/lib/ldap) puis relancer slapd

Pour visualiser et éditer le ldap, l'utilisation de shelldap est fortement
137
recommandée, en utilisant en binddn et basedn tous deux égaux à 'cn=config' et
Chirac's avatar
Chirac committed
138
binddpw le mot de passe admin.
139

140 141 142 143 144 145 146 147 148
Rajouter (exemple de chemin de fichier avec un certif LE):
`olcTLSCertificateKeyFile: /etc/letsencrypt/live/HOSTNAME/privkey.pem
olcTLSCACertificateFile: /etc/letsencrypt/live/HOSTNAME/chain.pem
olcTLSCertificateFile: /etc/letsencrypt/live/HOSTNAME/cert.pem `

Mettre à jour la partie ldap du `settings_local.py` (mettre 'TLS' à True
si besoin, user cn=config,dc=example,dc=org et mot de passe
ldap choisi précédemment).

Chirac's avatar
Chirac committed
149
## Configuration initiale
150

Chirac's avatar
Chirac committed
151
Normalement à cette étape, le ldap et la bdd sql sont configurées correctement.
152

Chirac's avatar
Chirac committed
153 154 155 156
Il faut alors lancer dans le dépot re2o '''python3 manage.py migrate''' qui
va structurer initialement la base de données.
Les migrations sont normalement comitées au fur et à mesure, néanmoins cette
étape peut crasher, merci de reporter les bugs.
157

Chirac's avatar
Chirac committed
158
## Démarer le site web
159

Chirac's avatar
Chirac committed
160 161
Il faut utiliser un moteur pour servir le site web. Nginx ou apache2 sont 
recommandés.
Chirac's avatar
Chirac committed
162 163 164
Pour apache2 :
 * apt install apache2
 * apt install libapache2-mod-wsgi-py3 (pour le module wsgi)
165

Chirac's avatar
Chirac committed
166 167
Un example de site apache2 se trouve dans install_utils ( re2o.conf)
re2o/wsgi.py permet de fonctionner avec apache2 en production
chirac's avatar
chirac committed
168

Chirac's avatar
Chirac committed
169
## Configuration avancée
chirac's avatar
chirac committed
170

Chirac's avatar
Chirac committed
171
Une fois démaré, le site web devrait être accessible. 
Chirac's avatar
Chirac committed
172 173
Pour créer un premier user, faire '''python3 manage.py createsuperuser''' 
qui va alors créer un user admin.
chirac's avatar
chirac committed
174 175 176
Il est conseillé de créer un user portant le nom de
l'association/organisation, qui possedera l'ensemble des machines, à indiquer
dans le menu reglages sur l'interface.
chirac's avatar
chirac committed
177

Chirac's avatar
Chirac committed
178 179 180 181 182 183 184
## Installations Optionnelles
### Générer le schéma des dépendances

Pour cela : 
 * apt install python3-django-extensions
 * python3 manage.py graph_models -a -g -o re2o.png

Chirac's avatar
Chirac committed
185
# Fonctionnement interne
186

Chirac's avatar
Chirac committed
187 188
## Fonctionnement général

Chirac's avatar
Chirac committed
189 190 191 192 193 194 195
Re2o est séparé entre les models, qui sont visible sur le schéma des 
dépendances. Il s'agit en réalité des tables sql, et les fields etant les 
colonnes.
Ceci dit il n'est jamais nécessaire de toucher directement au sql, django 
procédant automatiquement à tout cela. 
On crée donc différents models (user, right pour les droits des users, 
interfaces, IpList pour l'ensemble des adresses ip, etc)
Chirac's avatar
Chirac committed
196

Chirac's avatar
Chirac committed
197 198 199
Du coté des forms, il s'agit des formulaire d'édition des models. Il 
s'agit de ModelForms django, qui héritent des models très simplement, voir la 
documentation django models forms.
Chirac's avatar
Chirac committed
200 201 202

Enfin les views, générent les pages web à partir des forms et des templates.

203 204
## Fonctionnement avec les services

Chirac's avatar
Chirac committed
205
Les services dhcp.py, dns.py etc accèdent aux données via des vues rest.
Chirac's avatar
Chirac committed
206 207 208 209 210
Celles-ci se trouvent dans machines/views.py. Elles sont générées via 
machines/serializers.py qui génère les vues. IL s'agit de vues en json utilisées
par re2o-tools pour récupérer les données.
Il est nécessaire de créer un user dans re2o avec le droit serveur qui permet 
d'accéder à ces vues, utilisé par re2o-tools.
Chirac's avatar
Chirac committed
211 212 213 214

# Requète en base de donnée

Pour avoir un shell, il suffit de lancer '''python3 manage.py shell'''
Chirac's avatar
Chirac committed
215 216 217 218 219 220 221 222
Pour charger des objets, example avec User, faire : 
''' from users.models import User'''
Pour charger les objets django, il suffit de faire User.objects.all() 
pour tous les users par exemple. 
Il est ensuite aisé de faire des requètes, par exemple 
User.objects.filter(pseudo='test')
Des exemples et la documentation complète sur les requètes django sont 
disponible sur le site officiel.