Faire des qcm simplement - retour accueil
git clone git://bebou.netlib.re/qcm
Log | Files | Refs | README |
README (12285B)
1 # qcm
2
3 Faire des sondages simples en parsant les logs d'un serveur web
4
5 Sur un vieux concept déjà décrit
6 [ici](/sondages/#par-greppage-de-logs-de-serveurs-web). L'idée est d'en faire
7 une sorte de [kahoot !](https://kahoot.it/) ou
8 [wooclap](https://www.wooclap.com/fr/) like entièrement descriptible par un
9 fichier texte, ne nécessitant qu'un serveur accessible sur le web.
10
11 `qcm` est installé sur bebou mais uniquement les personnes ayant un compte
12 dessus peuvent l'utiliser pour créer des questionnaires. Il est cependant très
13 simple d'installer `qcm` sur votre serveur linux, et j'espère pas beaucoup moins
14 sur une autre variante Unix-like.
15
16 ## Dépendances
17
18 * un shell posix (testé avec dash et le sh d'openbsd)
19 * un `mktemp` avec `-d`
20 * un `grep` avec `--line-buffered` (GNU grep ou openbsd grep par ex)
21 * un `sed` posix
22 * un `xargs` posix
23 * un `ps` posix
24 * un `tail` avec -F (GNU tail l'a)
25 * optionnelle : gnuplot pour faire des graphiques avec -g
26
27 Testé sous debian 12 et le serveur web nginx packagé pour. Le code
28 parsant les logs convient pour le format par défaut d'nginx. Il se peut
29 qu'il ne fonctionne pas pour d'autres formats.
30
31 ## Les paramètres par défaut
32
33 url par défaut : http://bebou.netlib.re (modifiable dans le code)
34 log par défaut : `/var/log/nginx/access.log` (modifiable dans le code)
35 nombre de questions par défaut : 4 (ABCD)
36
37 ## Installation
38
39 Télécharger le code :
40
41 git clone git://bebou.netlib.re/qcm
42
43 Compiler et installer
44
45 cd qcm
46 make
47 make install
48
49 Il est possible de modifier le dossier de destination du script exécutable en
50 modifiant la variable `DEST` dans le makefile.
51
52 ## Usages et exemples
53
54 ### Créer des questionnaires
55
56 La syntaxe des questionnaires est [ici](#le-format-du-fichier-de-questionnaire).
57
58 #### Depuis le serveur web ou une machine ayant accès aux logs webs en direct
59
60 Lancer la console de création de questionnaire :
61
62 $ qcm
63
64 Pareil mais afficher une autre url (si jamais l'édition du script n'est pas
65 possible) :
66
67 $ qcm -u http://monsite.com
68
69 Comme le premier exemple mais scanner le fichier de log `/var/log/httpd/logs`
70 plutôt que celui par défaut (attention il faudra sûrement adapter le code) :
71
72 $ qcm -l /var/log/httpd/logs
73
74 Choisir l'identifiant du questionnaire pour qu'il soit "fraise". N'est pas
75 garanti de se lancer, il peut exister un questionnaire avec le même identifiant
76 :
77
78 $ qcm -i fraise
79
80 Choisir le dossier dans lequel le fichier HTML affichant les réponses sera créé.
81 Par défaut un fichier `index.html` sera créé dans un dossier `id`. Il faudra faire
82 F5 pour actualiser les résultats :
83
84 $ qcm -d /var/www/monsite
85
86 Lire un questionnaire déjà fait depuis stdin et afficher les résultats avec
87 gnuplot :
88
89 $ cat questionnaire.qcm | qcm -g
90
91 Lire un questionnaire et masquer les réponses tant que l'on a pas appuyé une
92 fois sur la touche entrée. Conviendrait pour un mode "examen" entre gros
93 guillemets :
94
95 $ cat questionnaire.qcm | qcm -e
96
97 #### Depuis une machine pouvant SSH sur le serveur web
98
99 Lancer un questionnaire sur un serveur équipé de `qcm` :
100 **Ne fonctionne pas encore**
101
102 $ cat questionnaire.qcm | ssh -t user@server qcm
103
104 Alternatives : uploader le fichier d'abord
105
106 $ cat questionnaire.qcm | ssh user@server 'cat > q'
107 $ ssh -t user@server '< q qcm;rm q'
108
109 ou copier/coller le fichier avec xclip :
110
111 $ < questionnaire.qcm xclip -selection clipboard
112 $ ssh -t user@server qcm
113 Ecrivez le questionnaire puis ctrl+D pour le soumettre
114 syntaxe du questionnaire :
115 http://arthur.bebou.netlib.re/qcm/#le-format-du-fichier-de-questionnaire
116 *ici faire ctrl+v pour coller le questionnaire*
117
118 ### Répondre aux questionnaires
119
120 Il faut se munir de l'url du serveur, de l'identifiant du questionnaire, de
121 l'intitutlé de la question et des choix de réponses. Ces infos sont connues de
122 la personne ayant créé le questionnaire.
123
124 Pour répondre à une question il faut créer et envoyer une requête HTTP GET au
125 serveur à l'url :
126
127 url/identifiant/réponse
128
129 Ainsi si l'url est `http://bebou.netlib.re`, l'identifiant `hjk` et la question
130 :
131
132 om, psg ou les verts ?
133
134 A om
135 B psg
136 C les verts
137
138 On pourra répondre "les verts" en envoyant la réquête à :
139
140 http://bebou.netlib.re/hjk/C
141
142 Quand cela est prévu il est possible de choisir plusieurs réponses. Il faut
143 alors bien les mettre dans l'ordre :
144
145 http://bebou.netlib.re/hjk/AC
146 et non pas
147 http://bebou.netlib.re/hjk/CA
148
149 Pour les questions ouvertes il est possible de répondre n'importe quoi
150
151 http://bebou.netlib.re/hjk/cool cool je peux écrire ce que je veux
152
153 Pour créer et envoyer cette requête le plus courant sera d'utiliser un
154 navigateur web et d'entrer l'url dans la barre d'url/de recherche en haut. Il
155 est également possible d'utiliser un programme comme `curl` ou `wget`.
156
157 Puisque les pages qui correspondent n'existent pas une erreur 404 sera
158 renvoyée. Pas d'inquiétude, la réponse a tout de même bien été prise en compte.
159
160 ### Consulter les réponses aux questionnaire
161
162 Si l'on est pas la personne créatrice du questionnaire et que l'on souhaite
163 consulter les réponses soit même on peut y accéder via l'URL configurée pour,
164 normalement affichée à l'écran de la personne créatrice. Si cette URL est
165 `monsite.fr` et le questionnaire a pour identifiant `aze` alors dans le
166 fonctionnement par défaut de `qcm` les résultats seront à
167 `http://monsite.fr/aze/index.html`.
168
169 Il est possible d'y accéder via un navigateur et de rafraichir les résultats
170 périodiquement ou, de manière plus automatisé :
171
172 watch -t curl -s http://monsite.fr/aze/ | sed '1d;$d'
173
174 Le `sed` permet de supprimer les balises `<pre>` et `</pre>`.
175
176 ## Le format du fichier de questionnaire
177
178 Le fichier de questionnaire est un fichier texte. Chaque question contient des
179 champs pour renseigner ses attributs et *doit* terminer par l'instruction
180 `demander`. Les attributs *doivent* être sous la forme `nom:` sans espace entre
181 le `:` et `nom` mais avec un espace après le `:`.
182
183 La liste des attributs :
184
185 * `question` : L'intitulé de la question. Optionnel. S'il n'existe pas rien
186 ne sera affiché
187 * `type` : le type de question. Optionnel.
188 * `qcm`, type par défaut, proposera un choix multiple (A, B, C...),
189 uniquement ces réponses seront valides. Si `options` existe il fera
190 correspondre les options aux différentes lettres. En l'absence
191 d'`options` `qcm` proposera 4 choix par défaut (A, B, C et D). Malgré
192 son nom `qcm` n'admet par défaut qu'une seule réponse possible. Voir
193 `choix`.
194 * `vote`, fonctionne comme `qcm` sauf que chaque option choisie est comptée
195 indépendamment. Répondre `ABC` ne comptera pas comme une réponse pour la
196 combinaison `ABC` mais comme une réponse pour `A`, une pour `B` et une
197 pour `C`. Plus approprié pour des votes. Utile pour se mettre d'accord
198 sur une date par exemple.
199 * `ouverte` permettra n'importe quelle réponse et ignore `options`.
200 * `regex` permet de restreindre les réponses possibles en écrivant un
201 expression régulière. Dans ce cas-ci `options` renseigne l'expression.
202 * `options` : Si la question est de type `qcm`, `options` est la liste des
203 réponses possibles séparées par des `~`. Il ne doit pas y avoir de `~` à la
204 fin. Si la question est de type `regex`, `options` est l'expression
205 régulière filtrant les réponses. Optionnel.
206 * `unique` : si une seule réponse par IP est autorisée ou pas. Optionnel. "non"
207 enregistrera toutes les réponses, n'importe quoi d'autre (`oui` par exemple)
208 filtrera sur les IP pour ne laisser que la première réponse passer. Par défaut
209 `unique` est à oui.
210 * `choix` : si la question est à choix multiple ou pas. Optionnel. "multiple"
211 permettra de choisir plusieurs options, n'importe quoi d'autre l'empêchera.
212 Par défaut les questions ne sont pas à choix multiple. Si la question est de
213 `type` `ouverte` cet attribut est ignoré puisqu'il n'y a pas d'options
214 parmi lesquelles choisir.
215 * `demander` : n'est pas un attribut mais "enregistre" la question et la lance
216
217 **Attention** : Tout attribut renseigné pour la N^ième question conservera sa
218 valeur pour les questions suivantes s'il n'est pas répété. Si la question ou
219 les réponses contiennent des caractères spéciaux `;/)'` etc il vaut mieux tout
220 "quoter" avec des ". Pour ajouter un `"` vous pouvez l'échapper avec un `\`.
221
222 Ainsi le fichier
223
224 demander
225
226 question: om, psg ou les verts
227 options: om~psg~les verts
228 choix: multiple
229 demander
230
231 question: Donnez un exemple de nombre réel svp
232 type: regex
233 options: [0-9]*[,.][0-9]+
234 unique: non
235 demander
236
237 question: "Quels sentiments vous évoquent l'anarchie ?"
238 type: ouverte
239 demander
240
241 question: "Sachant que :
242 x=3
243 y=7
244
245 Combien font \"x+y\" ?"
246 type: qcm
247 options: 6~11~10~autre
248 choix: unique
249 unique: oui
250 demander
251
252 question: Et x-y ?
253 demander
254
255 Posera six questions en tout.
256
257 1. celle par défaut, un qcm avec quatre choix, aucun intitulé, aucune réponse
258 possible d'affichée (juste les lettres). Par défaut ne permet de choisir
259 qu'une seule réponse une seule fois. Utile si les questions et les réponses
260 sont gérées par ailleurs, par exemple projetée via des diapos.
261 2. une qcm offrant le choix entre les trois équipes de foot. Il est possible
262 d'en choisir plusieurs à la fois. Est toujours un qcm par défaut et ne permet
263 de répondre qu'une seule fois.
264 3. une question `regex` demandant un nombre réel et filtrant sur une
265 expression régulière ne laissant passer que les nombres réels. Une même IP
266 peut envoyer plusieurs réponses.
267 4. une question ouverte à laquelle on peut répondre plusieurs fois. Notez les
268 `"` pour gérer l'apostrophe dans `l'anarchie`.
269 5. une question de type `qcm` de math dont une seule réponse est correcte et
270 à laquelle on ne peut répondre qu'une seule fois. Il faut ici rappeler que
271 c'est une qcm, que l'on ne peut répondre qu'une seule fois et qu'une seule
272 réponse est la bonne puisque par défaut on hérite des attributs de la
273 question précédente, ouverte et à laquelle on pouvait répondre plusieurs fois
274 ainsi que celle encore d'avant pour laquelle on pouvait choisir plusieurs
275 options. On notera également que si l'on englobe tout dans des `"` on peut
276 sauter des lignes et que l'on peut échapper des `"`.
277 6. identique à la question 5 mais l'intitulé change.
278
279 Étant donné que tous les attributs sont optionnels le fichier suivant :
280
281 demander
282 demander
283 demander
284
285 Est valide. Il posera trois questions sans intitulés avec quatre options de
286 réponses chacune.
287
288 Si l'on veut créer un questionnaire à la volée et que l'on connaît bien la
289 syntaxe ci-dessus on peut simplement lancer `qcm -f -` et écrire les questions.
290
291 ## Sécurité
292
293 **Attention !**
294
295 Les fichiers de questionnaire tel qu'ils fonctionnent aujourd'hui sont en
296 réalité des scripts (catium n'est jamais bien loin). Si entre deux attributs on
297 écrit `ls` la commande sera exécutée ! Cela peut être super pratique si l'on
298 fait confiance au script (automatiser des choses entre les questions ou écrire
299 du shell qui génèrera automatiquement les questions) mais cela est aussi un
300 immense risque d'un point de vue sécurité.
301
302 Il est donc fortement recommandé de limiter l'usage de cette fonctionnalité
303 à des sources réputées sûres. Par exemple, sur bebou, seules les personnes
304 détenant un compte peuvent utiliser `qcm`.
305
306 Il est possible de régler cette faille en réécrivant `qcm` pour qu'il parse le
307 fichier plutôt que l'exécuter mais c'est plus compliqué. Deux solutions
308 possibles :
309
310 1. lire ligne par ligne et exécuter le code mais uniquement si c'est une
311 fonction shell (vérifier si le script n'a pas accès à des fonctions autres
312 que celles déclarées dans le script lui même).
313 2. parser les lignes de façon à instancier les variables et faire les appels
314 "à la main".
315
316 Dans les deux cas il sera de toute façon délicat de garantir la sécurité et on
317 perd la possibilité de faire de la méta création de questionnaires.
318
319 ## BUG connus
320
321 Sur les questions ouvertes un accès aux résultats au chemin /id/index.html
322 comptera comme une réponse. Il faudrait éventuellement faire une exception pour
323 les chemins :
324
325 * `/id/index.html`
326 * `/id/`
327 * `/id`
328
329 sur les questions ouvertes.