Stalwart calendrier contacts

Stalwart calendrier contacts

Notes

Il y a deux choses distinctes : les paramètres du serveur (avec stalwart-cli) et les données des utilisateurs (événements, contacts), qui passent par d’autres chemins.

1. Paramètres calendrier et contacts

Ces réglages sont des objets uniques (« singletons ») : Calendar (limites iCalendar, noms par défaut), CalendarAlarm (notifications par courriel), CalendarScheduling (iTIP, RSVP) et AddressBook (stockage des contacts). Dans le WebUI, ils se trouvent sous Settings › Calendar & Contacts.

1
2
3
4
5
stalwart-cli describe Calendar           # liste des champs de votre version
stalwart-cli get Calendar
stalwart-cli get AddressBook
stalwart-cli get CalendarAlarm
stalwart-cli get CalendarScheduling

La documentation donne les formes stalwart-cli get address-book et stalwart-cli update address-book --field … pour ces singletons. Si address-book n’est pas reconnu, essayez AddressBook (votre CLI a accepté Authentication et Application en casse mixte). Les noms de champs varient avec la version, donc describe fait foi.

Exemple de modification : defaultDisplayName sur l’objet Calendar définit le nom du calendrier créé automatiquement, mais n’affecte que les nouveaux calendriers.

1
stalwart-cli update calendar --field defaultDisplayName=Agenda

2. Données (événements, contacts)

À ma connaissance, stalwart-cli ne sert pas à lire le contenu des agendas ou des carnets d’adresses : il pilote la configuration. Je n’ai pas trouvé de commande documentée pour les données. Vous avez deux accès directs, avec les identifiants du compte concerné (mot de passe, ou mot de passe d’application) :

CalDAV et CardDAV
Les collections de chaque compte sont servies sous /dav/cal et /dav/card, et /.well-known/caldav et /.well-known/carddav redirigent vers ces chemins.

1
2
3
4
5
6
7
# lister les agendas du compte
curl -u 'yann@yannig.net:MOT_DE_PASSE' -X PROPFIND -H 'Depth: 1' \
  https://yannig.net/dav/cal/yann%40yannig.net/

# lister les carnets d'adresses
curl -u 'yann@yannig.net:MOT_DE_PASSE' -X PROPFIND -H 'Depth: 1' \
  https://yannig.net/dav/card/yann%40yannig.net/

La réponse donne les href de chaque collection. Pour lire un élément, faites un GET sur son href : vous obtenez un .ics ou un .vcf.

JMAP
Interrogez https://yannig.net/jmap/session pour voir les capacités du compte (calendriers, contacts), puis utilisez les méthodes JMAP standard sur /jmap. Les noms de capacités et de méthodes sont à lire dans ce document de session.

Export ou sauvegarde en bloc
Les outils CalDAV/CardDAV classiques fonctionnent contre Stalwart. vdirsyncer synchronise un agenda ou un carnet vers un dossier local de fichiers .ics et .vcf, ce qui sert aussi de sauvegarde. khal et khard les lisent ensuite en ligne de commande.

Si vous cherchez un compte précis (ou un autre utilisateur depuis un compte administrateur), dites-moi lequel et ce que vous voulez en faire : lire, exporter ou restaurer. Je pourrai alors affiner la méthode.

Mise en forme xml

xmlstarlet (le plus proche d’un usage « requête + extraction »)

1
2
3
curl -s -u 'yann@yannig.net:MDP' -X PROPFIND -H 'Depth: 1' \
  https://yannig.net/dav/cal/yann%40yannig.net/ \
| xmlstarlet sel -N d=DAV: -t -m '//d:response' -v 'd:href' -n

Le -N d=DAV: déclare le préfixe de l’espace de noms WebDAV. Sans lui, les XPath ne trouvent rien, et c’est la cause d’échec la plus fréquente avec du DAV.

xmllint (inclus avec libxml2, souvent déjà installé)

1
... | xmllint --xpath '//*[local-name()="href"]' -

L’astuce local-name() évite de gérer les espaces de noms. Le résultat sort en XML brut : ajoutez | sed 's/<[^>]*>/\n/g' pour ne garder que le texte.

yq en mode XML (syntaxe proche de jq)

1
2
... | yq -p=xml -o=json '.'              # voir la structure d'abord
... | yq -p=xml '.multistatus.response[].href'

Il s’agit de yq de Mike Farah (Go). Les noms de clés gardent le préfixe d’origine (par exemple D:multistatus), donc regardez d’abord la sortie JSON. Il existe aussi xq, fourni par python-yq : il convertit le XML en JSON puis passe par jq, avec la syntaxe jq complète. Attention aux noms de paquets : sur Arch et Debian, yq désigne des programmes différents selon le dépôt.

Pour du XML « propre » ou en forme régulière, xq est le plus confortable si vous connaissez déjà jq. Pour du DAV avec espaces de noms, xmlstarlet reste le plus fiable.

Pour une sauvegarde quotidienne côté serveur, le plus simple est un export en lecture seule (rclone copy) vers un dossier que Borg sauvegarde déjà.

1. Créer mot de passe application sur le compte

Compte administrateur : une fois le compte créé, un mot de passe d’application ne s’ajoute plus par ce formulaire. Les mots de passe d’application et les clés d’API sont des identifiants secondaires, créés après le compte sous forme d’objets AppPassword et ApiKey. Ces objets n’ont pas de champ propriétaire : le credential appartient au compte qui exécute la requête. Il faut donc que l’appel soit fait par le compte concerné, ou en son nom par un administrateur.

compte yann@yannig.net

1
2
3
4
5
6
7
read -rs -p 'Mot de passe de yann@yannig.net : ' STALWART_PASSWORD; export STALWART_PASSWORD
export STALWART_URL=https://yannig.net
export STALWART_USER=yann@yannig.net

stalwart-cli create AppPassword \
  --field description='export-dav' \
  --field 'permissions={"@type":"Inherit"}'

La saisie avec read -rs évite de laisser le mot de passe dans l’historique du shell. Les options globales --url, --user et --password ont leurs équivalents STALWART_URL, STALWART_USER et STALWART_PASSWORD. La sortie affiche une ligne « Credential Secret: app_… » : copiez-la immédiatement, elle ne sera plus montrée.

1. Enregistrer le secret (remplacez par la valeur app_… affichée), puis effacer les variables du shell :

1
2
3
4
sudo mkdir -p /etc/stalwart-export/
printf '%s' 'app_xxxxxxxxxxxx' | sudo tee /etc/stalwart-export/yann.pw >/dev/null
sudo chmod 600 /etc/stalwart-export/yann.pw
unset STALWART_PASSWORD STALWART_USER STALWART_URL

Gardez aussi une copie du secret dans KeePassXC : si vous le perdez, il faudra en recréer un.

2. Tester l’accès DAV avec ce secret

1
2
3
curl -s -u "yann@yannig.net:$(sudo cat /etc/stalwart-export/yann.pw)" \
  -X PROPFIND -H 'Depth: 1' \
  https://yannig.net/dav/cal/yann%40yannig.net/ | head -c 600

Une réponse XML avec des href confirme que le mot de passe d’application est accepté en CalDAV. Refaites le test avec /dav/card/yann%40yannig.net/ pour les contacts.

2. Fichiers de configuration

/etc/stalwart-export/accounts.conf (permissions 600, propriétaire root), une ligne par compte, sous la forme adresse;fichier-du-mot-de-passe :

1
2
echo "yann@yannig.net;/etc/stalwart-export/yann.pw" | sudo tee /etc/stalwart-export/accounts.conf
sudo chmod 600 /etc/stalwart-export/accounts.conf

Chaque .pw ne contient que le mot de passe, en 600.

3. Script /usr/local/bin/stalwart-dav-export

Installer rclone

1
sudo apt install rclone

Créer le script

1
sudo nano /usr/local/bin/stalwart-dav-export
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/bin/bash
set -euo pipefail

BASE="https://yannig.net"
DEST="/var/backups/stalwart-dav"
CONF="/etc/stalwart-export/accounts.conf"

while IFS=';' read -r ACCOUNT PWFILE; do
  [ -z "${ACCOUNT:-}" ] && continue
  ENC="${ACCOUNT/@/%40}"
  PASS="$(rclone obscure "$(cat "$PWFILE")")"
  for KIND in cal card; do
    mkdir -p "$DEST/$ACCOUNT/$KIND"
    rclone copy ":webdav:" "$DEST/$ACCOUNT/$KIND" \
      --config /dev/null \
      --ignore-size \
      --webdav-url="$BASE/dav/$KIND/$ENC/" \
      --webdav-vendor=other \
      --webdav-user="$ACCOUNT" \
      --webdav-pass="$PASS" \
      --retries 3
  done
done < "$CONF"
1
sudo chmod 750 /usr/local/bin/stalwart-dav-export

Je mets copy plutôt que sync volontairement. Avec sync, un serveur qui renvoie un résultat vide ou incomplet effacerait l’export. Avec copy, les éléments supprimés restent dans le dossier, et l’historique de Borg garde de toute façon les versions. Si vous voulez un miroir exact, rclone sync avec --max-delete 20 limite les dégâts.

4. Service et Timer systemd

/etc/systemd/system/stalwart-dav-export.service :

1
2
3
4
5
6
7
[Unit]
Description=Export CalDAV/CardDAV Stalwart
After=network-online.target stalwart.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/stalwart-dav-export

/etc/systemd/system/stalwart-dav-export.timer :

1
2
3
4
5
6
7
8
9
[Unit]
Description=Export quotidien des calendriers et contacts

[Timer]
OnCalendar=*-*-* 02:30:00
Persistent=true

[Install]
WantedBy=timers.target

Activation

1
2
3
4
sudo systemctl daemon-reload
sudo systemctl enable --now stalwart-dav-export.timer
sudo systemctl start stalwart-dav-export.service   # premier essai
sudo journalctl -u stalwart-dav-export.service

Réglez 02:30 pour qu’il tourne avant votre sauvegarde Borg, et ajoutez /var/backups/stalwart-dav aux chemins sauvegardés. Le nom du service Stalwart (stalwart.service) est une supposition : adaptez-le.

Le journal journalctl -u stalwart-dav-export.service -o cat --since "-5min"

1
2
3
Starting stalwart-dav-export.service - Export CalDAV/CardDAV Stalwart...
stalwart-dav-export.service: Deactivated successfully.
Finished stalwart-dav-export.service - Export CalDAV/CardDAV Stalwart.

5. Vérifier et restaurer

Contrôle Agenda et Contacts

Contrôle : find /var/backups/stalwart-dav -name '*.vcf' | wc -l (et *.ics pour les agendas). Comparez avec le nombre attendu.

Compter les événements programmés dans les agendas :

1
2
   find /var/backups/stalwart-dav -name '*.ics' | wc -l
   grep -L 'END:VCALENDAR' /var/backups/stalwart-dav/yann@yannig.net/cal/*/*.ics

La seconde commande ne doit rien afficher. Les dossiers de cal portent le nom de vos agendas, ce qui permet de vérifier qu’ils sont tous là.

Compter le nombre de contact

1
   find /var/backups/stalwart-dav -name '*.vcf' | wc -l

Comparer 120 avec ce que vous attendez. Si vous avez 120 contacts dans CardBook ou DAVx⁵, c’est bon. Avec un nombre sensiblement inférieur ou supérieur, regardez s’il existe un deuxième carnet d’adresses : le script ne copie que les collections trouvées à la racine de l’URL.

Timer et Borg

Vérifier le timer :

1
   systemctl list-timers stalwart-dav-export.timer

Il doit afficher la prochaine exécution à 02:30.

1
2
NEXT                        LEFT LAST PASSED UNIT                      ACTIVATES                  
Thu 2026-11-19 02:30:00 CET  12h -         - stalwart-dav-export.timer stalwart-dav-export.service

Confirmer l’ajout à Borg : /var/backups/stalwart-dav doit figurer dans les chemins sauvegardés, et son exécution doit précéder celle de Borg.

Tester une restauration une fois : extrayez un .vcf d’une archive Borg et importez-le dans CardBook (ou vérifiez qu’il s’ouvre correctement). Une sauvegarde qu’on n’a jamais restaurée n’est pas vraiment validée.

Je peux aussi ajouter une notification ntfy en cas d’échec, comme pour vos mises à jour automatiques, si vous voulez être prévenu sans consulter le journal.

  • Restauration : récupérez les fichiers depuis Borg, puis importez-les par vdirsyncer (vu plus haut), ou par CardBook pour les contacts, puisque c’est l’outil qui fonctionne chez vous. Vous pouvez aussi tenter rclone copy dans l’autre sens, mais je ne l’ai pas validé pour Stalwart, donc testez sur un agenda de test.

Voulez-vous que j’ajoute une notification en cas d’échec (par exemple via ntfy, que vous utilisez déjà pour les mises à jour) ?