PAB's blog

La commande mysqldump est fort pratique pour effectuer une sauvegarde des bases de données sur un serveur MariaDB/MySQL. On peut bien sûr l'utiliser pour mettre en place des solutions de sauvegarde maison (cf. 2e section de la dépêche). On peut aussi utiliser le petit outil "automysqlbackup" que m'a conseillé Jdrien.

Une solution toute prête : automysqlbackup

Automysqlbackup est un petit script qui fera sans doute tout ce que vous cherchez (et peut-être plus !) : conservation de versions journalières, hebdomadaires des bases, utilisation de l'utilisateur par défaut Debian pour éviter d'avoir à saisir un mot de passe dans un script cron... Je vous laisse le découvrir dans cet article : http://jdrien.net/chronicus/index.php?article66/automysqlbackup-ou-l-art-de-ne-pas-reinventer-la-roue

Merci à Jdrien pour m'avoir présenté cette solution !

Une solution "maison" si automysqlbackup ne vous convainc pas :

Voilà un petit script pour automatiser intelligemment le processus. Prévu pour être lancé une fois par jour, le script effectue les actions suivantes :

• il liste les bases contenues sur le serveur
• il exporte chaque base dans un fichier nom_de_la_base.sql.X avec X le numéro du jour (1 pour Lundi, 2 pour Mardi...)

#!/bin/bash
nbday=$(date +"%u")
cd /chemin/backup/mysql
for i in *.sql.$nbday; do rm -f "$i"; done
mysql --user=debian-sys-maint --password="abcdef123456" -e 'show databases' | while read dbname; do mysqldump --user=debian-sys-maint --password="abcdef123456" "$dbname" > "$dbname".sql.$nbday; done

Détaillons le travail ligne à ligne.

On récupère le numéro du jour :

nbday=$(date +"%u")

On se place dans le dossier de sauvegarde des bases SQL :

cd /chemin/backup/mysql

On supprime les sauvegardes de la semaine passée :

for i in *.sql.$nbday; do rm -f "$i"; done

On parcourt la base de données et on exporte avec mysqdump le contenu de chaque base dans un fichier .sql.X (avec X le numéro du jour) :

mysql --user=debian-sys-maint --password="abcdef123456" -e 'show databases' | while read dbname; do mysqldump --user=debian-sys-maint --password="abcdef123456" "$dbname" > "$dbname".sql.$nbday; done

Vous noterez que l'accès à la base est effectuée avec l'utilisateur 'debian-sys-maint'. Cela n'est bien sûr valable que sur les sytèmes Debian. 'debian-sys-maint' est équivalent à un compte 'root' et le mot de passe paramétré par défaut pour ce compte se trouve dans /etc/mysql/debian.cnf. Utilisé par le système pour certaines fonctions de maintenance, il vous permettra dans ce cas de ne pas laisser votre mot de passe 'root' "à vous" en clair dans un fichier !

Bonnes sauvegardes !

Avec les bonnes règles, on peut demander à fail2ban de surveiller un certain nombre de services et de repérer toute tentative d'accès frauduleuse par force brute (i.e. essai de nombreuses combinaisons utilisateur/mot de passe possibles).

On crée d'abord un nouveau fichier de filtre dans /etc/fail2ban/filter.d/bruteforce.conf qui contient :

[Definition]
failregex = <insert here a regex to match in the log files> 
ignoreregex =

Il ne reste plus qu'à spécifier les règles (par expression régulière) nécessaires pour détecter les comportements coupables !

Pour protéger dotclear par exemple, on utilisera la règle suivante :

monblog.mondomain.tld:80 <HOST> - - .* "POST /admin/auth.php HTTP/1.1" 200

Pour Wordpress, on pourra utiliser celle-là :

monblog.mondomain.tld:80 <HOST> - - .* "POST /wp-login.php HTTP/1.1" 200

Et pour Piwik, celle-ci pourra faire l'affaire :

monpiwik.mondomain.tld:80 <HOST> - - .* "POST / HTTP/1.1" 200

Les dernières étapes consistent à ajouter une section dans le fichier /etc/fail2ban/jail.local pour utiliser ces nouveaux filtres et surveiller le fichier de log d'apache !

[apache-services-bruteforce]
enabled  = true
port     = http,https
filter   = bruteforce
logpath = /var/log/apache2/other_vhosts_access.log
maxretry = 8

La grande frousse pour de nombreux administrateurs (enfin j'imagine), c'est la panne d'un système critique (généralement un samedi matin) qui passe inaperçue... Je vais vous présenter ici le petit utilitaire 'monit' qui, tout simplement, vous permettra de recevoir des notifications en cas de panne d'un de vos services. Et d'effectuer un ensemble de réactions ! C'est très certainement l'allié indispensable aux côtés de Munin que je présentais dernièrement !

Monit (à ne pas confondre avec M/Monit qui est son grand-frère non libre) est un ingénieux petit logiciel auquel on donne des missions de surveillance et des actions à effectuer lorsque certains comportements sont constatés. Je ne résiste pas à la tentation de recopier ici la bannière trouvée sur le site de monit :

Un cas typique d'utilisation est le suivant : vous avez un processus P qui doit tourner sur votre machine mais que vous craignez voir s'arrêter... Vous pouvez demander à monit de vérifier toutes les X minutes que ce processus tourne toujours et le redémarrer si monit le trouve éteint. Dans ce cas, vous exécuterez monit sur le serveur qui propulse le processus à surveiller.

Autre scénario : votre serveur HTTP tourne sur l'adresse 2000:aaaa:bbbb:: et le port 80 et vous voulez vous assurer qu'il est toujours joignable. Monit peut se connecter à cette IP (ping) et dialoguer avec le service (voire même effectuer des requêtes HTTP complètes et évaluer la réponse) pour déterminer s'il est vivant. Et cela peut également fonctionner pour surveiller un FTP, un IMAP, un serveur OpenVPN... Dans ce cas, on hébergera monit sur le serveur local ou bien à distance si l'on souhaite également détecter une perte de connectivité (attention toutefois au cas de la coupure du serveur chargé de la surveillance !).

Et Monit permet bien plus encore : vérifier la présence d'un fichier, vérifier les droits sur un dossier, vérifier que la charge CPU ou la mémoire vive n'ont pas éteint des niveaux trop élevés et agir si nécessaire... Monit voit et agit !

L'installation de monit s'effectue (sous Debian) par un classique :

aptitude install monit

Pour le paramétrage, on parcourra d'abord /etc/monit/monitrc :

# Vérifier l'état des services toutes les 2 minutes
set daemon 120
# Raconter le quotidien dans un fichier
set logfile /var/log/monit.log
# Communiquer avec l'ami SMTP pour envoyer des courriels d'alerte
set mailserver monsmtp.domain.tld username "Moi" password "MonMDP" using tlsv1
# Choisir l'expéditeur de son choix quand Monit nous parle
set mail-format { from: monit@monserveur.domain.tld }
# Choisir à qui les alertes sont envoyées
set alert mon@courriel.fr
# Inclure les éléments de configuration compris dans /etc/monit/conf.d/
include /etc/monit/conf.d/*

On pourra s'occuper du ménage concernant le fichier de log (/var/log/monit.log) à l'aide de logrotate comme expliqué ici (section 'envie de rotation?').

Entrons alors dans le vif du paramétrage...

check host monsite.domain.tld with address a.b.c.d
 if failed icmp type echo count 3 with timeout 3 seconds then alert
 if failed port 80 protocol http with timeout 15 seconds then alert
 if failed port 1194 type udp with timeout 15 seconds then alert

La routine ci-dessous ne fait qu'envoyer des alertes : (i) si le serveur ne répond plus au ping, (ii) si un serveur web ne répond plus sur le port 80 et (iii) si un service ne répond pas en UDP sur le port 1194 (OpenVPN par exemple). Monit exécute chaque test les uns après les autres. Lorsqu'un test échoue au sein d'un groupe alors les tests suivants ne sont pas effectués. Monit envoie automatiquement un message lorsque le service est perdu et prévient également (c'est bien aimable de sa part) quand le service est rétabli.

Plus ardu :

check process apache with pidfile /usr/local/apache/logs/httpd.pid
  start program = "/etc/init.d/httpd start" with timeout 60 seconds
  stop program  = "/etc/init.d/httpd stop"
  if cpu > 60% for 2 cycles then alert
  if cpu > 80% for 5 cycles then restart
  if totalmem > 200.0 MB for 5 cycles then restart
  if children > 250 then restart
  if loadavg(5min) greater than 10 for 8 cycles then stop
  if failed host www.tildeslash.com port 80 protocol http
      and request "/somefile.html"
      then restart
  if failed port 443 type tcpssl protocol http
     with timeout 15 seconds
     then restart
  if 3 restarts within 5 cycles then timeout
  depends on apache_bin
  group server

Le script ci-dessous adopte le comportement suivant :

• une alerte est émise sur la charge CPU est supérieure à 60% au cours de 2 vérifications successives
• le serveur Apache est redémarré si la charge CPU est supérieure à 80% au cours de 5 vérifications successives
• le serveur Apache est redémarré si la mémoire consommée est supérieure à 200 MB au cours de 5 vérifications successives
• le serveur Apache est redémarré si plus de 250 processus fils sont détectés
• le serveur Apache est stoppé (pas redémarré) si la charge est supérieure à 10 pendant 8 vérifications
• le serveur Apache est redémarré si l'hôte www.tildeslash.com ou l'appel du fichier somefile.html échouent
• le serveur Apache est redémarré si l'accès en HTTPS n'est pas disponible
• et enfin si 3 redémarrages sont constatés en 5 cycles alors on passe à une alerte de niveau supérieur (timeout)

Je ne couvre ici qu'une faible part des possibles et je vous invite à explorer ! Un superbe outil à mettre dans toutes les mains !

Si votre serveur Web se trouve "caché" derrière un "reverse proxy" ou toute forme de "load balancer", alors vous serez peut-être embêté en constatant que les logs d'accès d'Apache ne mentionnent par défaut que l'adresse du proxy comme adresse d'origine... Ennuyeux !

Heureusement, les esprits ingénieux qui ont conçu les "reverse proxies" ont pensé à ajouter aux paquets transmis le drapeau "X-Forwarded-For". Il suffit alors de demander à votre serveur web de prendre en compte l'IP spécifiée dans ce champ comme origine de la communication !

Dans le cas d'Apache2, la configuration intiale qui était :

LogFormat "%v:%p %h %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" vhost_combined
LogFormat "%h%l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" combined
LogFormat "%h %l %u %t "%r" %>s %O" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent

devient (on remplace %h par %{X-Forwarded-For}i) :

LogFormat "%v:%p %{X-Forwarded-For}i %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" vhost_combined
LogFormat "%{X-Forwarded-For}i %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" combined
LogFormat "%{X-Forwarded-For}i %l %u %t "%r" %>s %O" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent

Pour les logs d'erreur (importants par exemple pour permettre à fail2ban, ou un autre démon du genre, d'agir), la version 2.2 d'Apache ne permet malheureusement pas de prendre en compte un format spécifique pour les logs. Il semble que cela soit corrigé dans la version 2.4 d'Apache (cf. ici). Si vous utilisez la version 2.2, alors il faudra installer le module rpaf :

aptitude install libapache2-mod-rpaf
a2enmod rpaf

puis dans /etc/apache2/conf.d/mod_rpaf :

RPAFenable On
RPAFsethostname On
RPAFproxy_ips a.b.c.d e.f.g.h
RPAFheader X-Forwarded-For

en remplaçant a.b.c.d et e.f.g.h par les adresses du reverse proxy. RPAF va veiller, dans les logs d'erreur, à remplacer l'adresse du 'reverse proxy' par l'adresse du client telle que signalée dans "X-Forwarded-For".

Et le tour est joué !

Dans cet article, nous allons voir comment faire communiquer un onduleur Eaton Ellipse 650 (mais le mode opératoire peut s'adapter à d'autres modèles d'onduleurs compatibles avec Linux) et un Raspberry Pi sous Raspbian. Le Raspberry Pi pourra alors accomplir une série d'actions : par exemple, dans le cas exposé ici, envoyer une notification de coupure électrique par courriel.

On commence par installer l'utilitaire NUT sous Linux :

aptitude install nut nut-usb

Puis on choisit le mode STANDALONE dans /etc/nut/nut.conf. Ensuite on ajoute un paragraphe correspondant à l'onduleur connecté en USB au Raspberry Pi dans /etc/nut/ups.conf :

[eaton]
driver = usbhid-ups
port = auto
desc = "MGE UPS Systems"

On peut alors vérifier que la connexion à l'onduleur fonctionne par la commande :

/lib/nut/usbhid-ups -DDD -a eaton

SI l'utilitaire nous retourne une erreur similaire à "failed to claim USB device" alors cela peut signifier que les droits ne sont pas suffisants pour accéder à la ressource. On peut alors essayer la connexion avec la commande :

/lib/nut/usbhid-ups -DDD -u root -a eaton

Si cela fonctionne, on pourra alors régler (attention, c'est une méthode un peu brutale !) le problème en modifiant la section "usbfs-like devices" du fichier /lib/udev/rules.d/91-permissions.rules :

 SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", \
-                               MODE="0664"
+                               MODE="0666"

(attention au risque potentiel de sécurité de cette modification, à n'effectuer qu'en connaissance de cause !)

Une fois l'onduleur correctement reconnu, on ajoutera un utilisateur à la liste des utilisateurs autorisés à se connecter au service de l'onduleur. Ce paramétrage s'effectue en modifiant le fichier /etc/nut/upsd.users - on ajoutera par exemple

[utilisateur]
        password = monmotdepasse
        upsmon master

Enfin, on modifiera le fichier /etc/nut/usbmon.conf pour modifier les options de suivi :

MONITOR eaton@localhost 1 utilisateur monmotdepasse master

On pourra spécifier un script spécifique à exécuter lors des événements électriques :

NOTIFYCMD /path/to/notification/script

Et on pourra modifier le contenu des messages à envoyer pour chaque événement électrique reconnu :

NOTIFYMSG ONLINE        "Electrical power is back ON - UPS %s on line power"
NOTIFYMSG ONBATT        "Loss of electrical power - UPS %s on battery"
NOTIFYMSG LOWBATT       "Loss of electrical power continues - UPS %s"

Pour chaque état de l'onduleur, on pourra spécifier les actions à effectuer : - EXEC = exécuter le script de notification paramétré plus haut - SYSLOG = mentionner l'événement dans le syslog du système - WALL = faire apparaître le message dans la console de tous les utilisateurs connectés

NOTIFYFLAG ONLINE       EXEC+SYSLOG+WALL
NOTIFYFLAG ONBATT       EXEC+SYSLOG+WALL
NOTIFYFLAG LOWBATT      EXEC+SYSLOG+WALL

On pourra par exemple utiliser un scrit de notification de la sorte :

#! /bin/bash
#Send email with detailed UPS report
o=$(upsc eaton)
d=$(date)
echo -e "$d" "\n\nEvent: " "$*" "\n\n======Details on UPS=====\n" "$o" |mail -s "Evénement électrique" courriel@domain.tld
#Add any other actions: send SMS, launch shutdowns of critical systems...

Bonne surveillance de votre onduleur !

Un RAID 1 (mirroring) constitue ne bonne garantie contre une panne de disque dur sur une machine (serveur, poste de bureau, NAS) contenant des données critiques. Avec une bonne maintenance, on peut espérer conserver des données avec un faible taux de risque de perte sur de longues durées : une bonne méthode consistant par exemple à ajouter des disques plus récents à la grappe RAID.

Nous allons détailler ici les opérations nécessaires pour ajouter un disque dur de X Go à une grappe (RAID 1) de 2 disques durs de même capacité, gérée par les fonctionnalités de RAID logiciel sous Linux.

La première étape consiste à copier la table des partitions des disques durs actifs dans le RAID (appelons les /dev/sda et /dev/sdb) sur le nouveau disque (/dev/sdc). En effet, le nouveau disque doit être structuré (en termes de partitions) rigoureusement comme les anciens.

Attention, il existe aujourd'hui couramment deux types de table de partition : l'ancien système à base de MBR (Master Boot Record) et le nouveau système nommé GPT (Globally Unique Identifier Partition Table). En MBR, vous pouvez utiliser l'utilitaire fdisk/sfdisk (non détaillé ici). Si vos disques sont formatés avec des tables GPT (le nouveau standard), voici comment faire.

On enregistre d'abord la table de partition du disque sda dans un fichier 'table' :

sgdisk --backup=table /dev/sda

puis on applique cette table au disque /dev/sdc (attention à ne pas se tromper de disque, cela pourrait être destructeur !) :

sgdisk --load-backup=table /dev/sdc

Et comme dans le système GPT chaque partition est identifiée par un unique GUID et que celui-ci est inclus dans la table GPT, alors il faut modifier les GUID pour des valeurs aléatoires dans le disque fraîchement ajouté :

sgdisk -G /dev/sdc

Le nouveau disque dur est maintenant prêt à intégrer le RAID.

mdadm --detail /dev/md0

va nous permettre de regarder les partitions inclues dans cette première partition en RAID. Par exemple, on verra que ce sont les partitions /dev/sda2 et /dev/sdb2 qui sont concernées. On saura donc qu'il faut ajouter /dev/sdc2 :

mdadm --manage /dev/md0 --add /dev/sdc2

Puis

mdadm --detail /dev/md0

doit montrer que le nouveau disque a été ajouté.

Il est toutefois fort probable que le disque ait été monté en 'spare device' i.e. en périphérique activé uniquement en cas de perte d'un autre disque. Si vous souhaitez que les données soient répliquées dès maintenant sur ce disque, il faudra agrandir le RAID :

mdadm --grow /dev/md0 --raid-devices=3

Et le tour est joué, la reconstruction du RAID (i.e. la copie des données vers le nouveau disque) doit s'effectuer de manière transparente. /dev/md0 est désormais répliqué sur 3 disques durs.

Bien sûr, une procédure similaire pourra être déployée en cas de disque défectueux pour ajouter un nouveau disque dans la grappe !

J'utilise souvent demo.ovh.eu (le service de partage mis en place par OVH, qui, contrairement à beaucoup d'autres, n'oblige pas à visualiser des publicités) pour partager aisément des fichiers sur internet. Toutefois, je souhaiterais parfois que le fichier soit effacé après téléchargement et savoir quand celui-ci a été téléchargé. Certains services proposent sans doute cela et l'outil Jyraphe (dont le développement est stoppé ?) le permet. Je vous propose toutefois une solution maison toute simple à mettre en place et extrêmement simpliste à déployer sur serveur web + PHP !

Soit le fichier mon_archive.7z à proposer au téléchargement. Soit /var/www/ la racine du serveur web accessible sur le net. On place le fichier mon_archive.7z dans un dossier /var/www/hidden/ qu'un fichier .htaccess protège de toute ouverture. On place ensuite le code suivant dans un fichier /var/www/telechargement-ici_chaîne_unique_non_devinable.php :

<?php
    $yourfile = "hidden/mon_archive.7z";

    if (file_exists($yourfile)) {
        $file_name = basename($yourfile);

        header("Content-Type: application/zip");
        header("Content-Disposition: attachment; filename=$file_name");
        header("Content-Length: " . filesize($yourfile));

        readfile($yourfile);
        unlink($yourfile);
        if (file_exists($yourfile)) {
            mail('moi@courriel.fr', 'Fichier téléchargé mais pas supprimé !', 'Le fichier "'.$file_name.'" a bien été téléchargé par '.$_SERVER["REMOTE_ADDR"].' et n\'a pas été supprimé.');
        }
        else {
            mail('moi@courriel.fr', 'Fichier téléchargé et supprimé !', 'Le fichier "'.$file_name.'" a bien été téléchargé par '.$_SERVER["REMOTE_ADDR"].' et a été supprimé.');
        }
    }
    else {
        print "Unknown file...";
        mail('moi@courriel.fr', 'Tentative de téléchargement infructueuse.', 'Qqn ('.$_SERVER["REMOTE_ADDR"].') a tenté en vain de télécharger le fichier "'.$yourfile.'".');
    }
    exit;
?>

Le fichier php propose donc le fichier au téléchargement quand l'utilisateur appelle https://monserveur/telechargement-1g2j0a7j8.php puis l'efface du serveur et vous préviens (par courriel) que le téléchargement a eu lieu. Il enregistre également l'adresse IP de la personne qui a effectué le téléchargement (certes, c'est très approximatif comme identification). Le mot de passe est en fait la chaîne arbitrairement complexe et longue placée dans l'URL pour accéder au fichier .php permettant le téléchargement.

On pourrait améliorer encore la sécurité en récupérant le mot de passe (la chaîne arbitraire) dans un paramètre GET (?pass=1g2j0a7j8 par exemple) et bannir une IP qui ferait plus de 3 ou 4 tentatives d'accès infructueuses.

Le cahier des charges est respecté, ce n'est pas tout à fait automatique mais ça ne devrait pas être trop difficile à scripter si vous avez de nombreux fichiers de la sorte à mettre à disposition. Et surtout, votre archive (peut-être très confidentielle) ne transite pas sur un serveur tierce.

Depuis fort longtemps, Firefogg est mon allié de choix quand il s'agit de convertir une vidéo vers le format webM (plus d'infos ici et ici), libre, efficace et reconnu par de nombreux navigateurs.

Ainsi, au mariage d'un beau-frère, quand je devais finaliser LA vidéo qui allait faire pleurer belle-maman, rire beau-papa et faire swinger les mariés, je comptais sur Firefogg pour m'aider comme à l'accoutumée.

C'était sans compter sur l'absence d'internet ! Impossible de lancer Firefogg sur mon ordinateur coupé d'internet (jolie salle de mariage isolée oblige, pas de réseau téléphonique non plus...). O rage et désespoir !

En effet, Firefogg ne se lance pas s'il ne se connecte pas à la page http://firefogg.org/. Il ne s'agit bien sûr pas d'une compression réalisée sur un serveur distant mais la conception même de Firefogg demande une page web. Firefogg a été pensé comme un plugin mobilisable par un site internet pour déporter la compression d'une vidéo sur le poste client (et ensuite la rapatrier sur le service en ligne). Il est donc nécessaire, pour mettre en branle Firefogg, de l'appeler au travers d'une API JavaScript. C'est ce que la page http://firefogg.org/ fournit par défaut.

Il suffisait de le savoir et d'avoir éventuellement la-dite page (ou tout sous-ensemble compatible avec l'API) avec soi en local. En suivant ce lien, vous trouverez une copie au 5 septembre 2013 de la page http://firefogg.org/. Elle permet de lancer Firefogg en absence de toute connexion internet. Utile dans certaines situations !

PS Pour ceux qui s'inquiètent, j'ai réussi à sauver ma journée cette fois-là en encodant à l'aide de ffmpeg... qui lui n'a *vraiment* pas besoin d'internet, nah !

PS2 En suivant cet autre lien, un patch au plugin Firefogg qui ajoute un bouton "Make Video Offline"... à toute fin utile !

Nous allons décrire ici comment générer une carte de France à partir de Kartograph.py et l'afficher avec des données à l'aide de Kartograph.js.

Kartograph.py et Kartograph.js sont deux librairies libres (open source et sous licence LGPL) développées par Gregor Aisch et disponibles ici : http://www.kartograph.org.

La première, Kartograph.py écrite en python, permet de générer des fonds de carte sous forme vectorielle (fichier *.svg) avec des tracés géoréférencés.

La seconde, Kartograph.js écrite en javascript, qui s'appuie sur la librairie de manipulation d'objets vectoriels RaphaelJS, parcourt le fichier vectoriel généré par Kartograph.py et affiche la carte au sein d'une page web. Il est également possible d'ajouter des données géographiques sur la carte à l'aide de l'API Kartograph.js.

Générer un fond de carte de France

Les données géographiques source sont disponibles sur GADM. L'archive française contient 5 niveaux d'information : FRA_adm0 contient les frontières nationales, FRA_adm1 contient les frontières des régions françaises, FRA_adm2 contient les tracés des départements, FRA_adm3 inclut les tracés des arrondissements, FRA_adm4 les tracés des cantons et enfin FRA_adm5 les tracés des villes.

La génération de la carte s'effectue à l'aide de l'outil Kartograph.py en lui spécifiant un certain nombre de paramètres à l'aide d'un fichier .json.

Voici un exemple de fichier :

{
    "layers": {
        "boundaries": {
		      "src": "FRA_adm0.shp",
		      "simplify": 3,
		      "attributes": ["ISO", "NAME_ISO"]
	      },
        "regions": {
		      "src": "FRA_adm1.shp",
		      "simplify": 3,
		      "attributes": ["ISO", "NAME_1"]
	      },
	      "departments": {
		      "src": "FRA_adm2.shp",
		      "simplify": 3,
		      "attributes": ["ISO", "NAME_1"]
	      },
	      "background": {
          "special": "sea"
        }
    },
    "proj": {
        "id": "laea",
        "lon0": 2.37556359389,
        "lat0": 49.9701576233
    }
}

On voit que ce fichier définit 2 catégories d'objet : des calques (layers) et une projection. On note que plusieurs calques sont créés et que pour chacun on précise : - "src" : la source de données sous la forme d'un fichier ShapeFile (*.shp) - "simplify" : un degré de simplification du tracé pour réduire la taille du svg généré - "attributes" : la liste des méta-données (informations) que l'on souhaite voir inclus dans le fichier vectoriel. Les données inclues dans le vectoriel seront accessibles depuis Kartograph.js. Chaque calque pourra être traité séparément par Kartograph.js, notamment avec des styles différents pour chacun.

Quand les paramètres de la carte sont satisfaisants, on lance la génération à l'aide de :

kartograph mes_parametres.json -o fichier_genere.svg

Le traitement peut prendre plusieurs minutes et le fichier est généré.

Dans le cade de l'exemple, voici le fichier .svg généré :

Utilisation du fond de carte dans une page web

La page web à créer doit contenir les librairies Javascript RaphaelJS, JQuery et Kartograph.

        <script src="lib/jquery.min.js"></script>
        <script src="lib/raphael.min.js"></script>
        <script src="lib/kartograph.min.js"></script>

Le fichier doit également contenir un bloc div dans lequel la carte sera placée :

    <body>
        <div id="map"></div>
    </body>

et le javascript suivant permet de générer la carte :

          var map = kartograph.map('#map'); // #map fait référence au div répondant à id="map"
          map.loadMap('fr.svg', function() {
            // ici, on précisera toutes les options pour l'affichage sur le carte
          }, {padding: "20"} );

Comme on peut le voir avec l'option {padding: "20"}, certains paramètres d'affichage peuvent être placés sous forme de dictionnaire après la fonction de génération.

Au sein de la fonction de génération, on ajoute la définition des couches à construire :

            map.addLayer('departments', {
                styles: {
                  'stroke-width': 1,
                  'stroke': "#C0C0C0",
                  'fill': "#fff"
                }
            });

L'exemple précédent récupère la couche 'departments' (qui avait été créé dans le fichier .json défini plus haut) et l'affiche avec les options de style (couleur et épaisseur du trait, couleur de remplissage) définies ici.

On peut ensuite ajouter des objets sur le carte à l'aide de la fonction 'addSymbols'. Par exemple, pour ajouter une bulle,

            map.addSymbols({
                type: kartograph.Bubble,
                data: myData,
                location: function(item) {
                    return [item.lon, item.lat];
                },
                radius: function(item) {
                    return item.radius;
                },
                sortBy: 'radius desc',
                style: function(item) {
                    return 'fill:'+item.color+';';
                },
            });

Dans l'exemple précédent, on récupère les données depuis un tableau myData contenant une collection d'objets aux caractéristiques lon/lat/radius/color. D'autres types sont possibles : kartograph.Label, kartograph.PieChart, kartograph.StackedBar...

Pour ajouter des formes diverses, on peut utiliser la fonction :

map.addGeoPath([kartograph.LonLat(lon1, lat1),kartograph.LonLat(lon2, lat2)]).attr( 'stroke-width', '2');

Les objets sont des objets RaphaelJS et il est donc possible d'utiliser toutes les fonctions de RaphaelJS pour attribuer des styles ou des comportements.

L'outil permet d'obtenir de jolies cartes et représentant les jeux de données que l'on souhaite. De nombreux exemples (avec le code source correspondant) sont disponibles ici : http://kartograph.org/showcase/.