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