From 841ed1a79914e021a16bf36537f496b4600bd79d Mon Sep 17 00:00:00 2001 From: yann Date: Sat, 24 May 2025 12:16:43 +0200 Subject: [PATCH] README FR --- LISEZMOI.md | 245 -------------------------------------------------- README.md | 178 ++++++++++++++++++------------------ README_EN.md | 249 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 336 insertions(+), 336 deletions(-) delete mode 100644 LISEZMOI.md create mode 100644 README_EN.md diff --git a/LISEZMOI.md b/LISEZMOI.md deleted file mode 100644 index 8a9581f..0000000 --- a/LISEZMOI.md +++ /dev/null @@ -1,245 +0,0 @@ -# wg-meshconf - -wg-meshconf est un outil qui vous aidera à générer des fichiers de configuration par les pairs pour les réseaux de mailles WireGuard. Vous pouvez facilement et rapidement créer des réseaux de mailles WireGuard à l'aide de cet outil. - -## Installation (pipx) - -Installer Pipx sous Linux - -```shell -python -S python-pipx -``` - -Avoir le bon chemein - -```shell -pipx ensurepath -``` - -Résultat commande - -``` -Success! Added /home/yann/.local/bin to the PATH environment variable. - -Consider adding shell completions for pipx. Run 'pipx completions' for instructions. - -You will need to open a new terminal or re-login for the PATH changes to take effect. -Alternatively, you can source your shell's config file with e.g. 'source ~/.bashrc'. - -Otherwise pipx is ready to go! ✨ 🌟 ✨ -``` - -Rafraîchir pour prise en compte de la modification du chemin (path) - -```shell -source ~/.bashrc -``` - -**pipx, est la façon recommandée d'installer wg-meshconf pour les utilisateurs réguliers**. Cette méthode d'installation installe la dernière version de version de wg-meshconf et toutes les dépendances requises de PyPI. - -```shell -# installing the program with pipx -pipx install wg-meshconf - -# running the program -wg-meshconf showpeers -``` - -## Apprendre par un exemple - -Voyons un exemple réel de la façon dont cet outil peut être utilisé. Cette section montrera comment créer un réseau de mailles simple avec quatre nœuds en utilisant wg-meshconf. - -Pour cet exemple, supposons que vous ayez quatre serveurs comme indiqué ci-dessous. Ces serveurs peuvent se rejoindre par l'adresse `Endpoint`. Par exemple, le serveur `tokyo1` peut ping server `shanghai1` avec l'adresse `shanghai1.com`. - -![image](https://user-images.githubusercontent.com/21986859/99200153-94839e80-279b-11eb-81c9-189b609661ee.png) - -### Étape 1 : Ajouter la base Information Pair (Peer) - -Vous devrez d'abord ajouter l'information des pairs dans la base de données. -Il y a deux façons de le faire : - -* via Excel -* via l'interface de ligne de commande. - -#### Méthode A: Avec Excel - -wg-meshconf a changé son format de base de données de JSON à CSV et a ajouté la commande `init` depuis la version 2.4.0. Cela signifie qu'il est maintenant possible pour les utilisateurs de modifier directement le fichier de base de données avec Excel ou d'autres éditeurs compatibles CSV pour créer/lire/update/effacer l'information des pairs. - -Exécutez la commande suivante pour initialiser un nouveau fichier de base de données. Par défaut, le fichier de base de données est nommé `database.csv`. Vous pouvez également spécifier le nom du fichier via `-d`. - -```shell -wg-meshconf init -``` - -Ouvrez le fichier CSV avec un éditeur comme Excel ou LibreOffice Calc. Vous devriez voir les en-têtes de colonne suivantes. - -![image](https://user-images.githubusercontent.com/21986859/120080963-93b4b900-c0aa-11eb-9e40-0da767c1cbfc.png) - -Vous pouvez ensuite remplir l'information des pairs. **Vous devrez remplir au moins les valeurs `Nom`, `Adresse` et `Endpoint` des pairs.** Ces valeurs ne peuvent pas être générées automatiquement. - -![image](https://user-images.githubusercontent.com/21986859/120081082-2fdec000-c0ab-11eb-90ad-0993a0557e1e.png) - -Une fois que vous avez terminé, enregistrez le fichier et exécutez à nouveau la commande `init` pour générer automatiquement le reste des informations nécessaires telles que les clés privées de pair. - -```shell -wg-meshconf init -``` - -Si vous vérifiez à nouveau le fichier, vous verrez les champs nécessaires se déposer automatiquement. - -![image](https://user-images.githubusercontent.com/21986859/120081172-a2e83680-c0ab-11eb-963d-b6810a6580a3.png) - -#### Méthode B: Avec terminal - -Si, pour une raison quelconque, vous ne voulez pas modifier le fichier de base de données directement, vous pouvez également utiliser cet outil uniquement via son interface en ligne de commande. - -D'abord, nous devons ajouter tous les pairs du réseau de maillé dans la base de données. La syntaxe de base pour ajouter de nouveaux pairs est : - -```shell -wg-meshconf addpeer NAME --address IP_ADDRESS --address IP_ADDRESS_2 --endpoint ENDPOINT -``` - -- Une nouvelle clé privée sera générée automatiquement si non spécifiée -- ListenPort par défaut à 51820 , standard WireGuard -- Toutes les autres valeurs restent vides par défaut - -Il y a d'autres options que vous pouvez spécifier. Utilisez la commande `wg-meshconf addpeer -h` pour plus de détails. - -Après avoir ajouté tous les pairs dans la base de données, vous pouvez vérifier qu'ils ont tous été ajoutés correctement via la commande `wg-meshconf showpeers`. Le commutateur `simplify` omet ici toutes les colonnes avec seulement `None`s. - -![image](https://user-images.githubusercontent.com/21986859/99202459-1dec9e00-27a7-11eb-8190-a5a3c6644d2a.png) - -### Étape 2: Exporter les fichiers de configuration - -Utilisez la commande `genconfig` pour générer des fichiers de configuration pour tous les pairs. Vous pouvez également exporter des configurations pour un seul pair en spécifiant le nom du pair. - -Les fichiers de configuration seront nommés d'après les noms des pairs. Par défaut, tous les fichiers de configuration sont exportés dans un sous-répertoire nommé `output`. Vous pouvez modifier cela en spécifiant le répertoire de sortie en utilisant l'option `-o` ou `--output`. - -![image](https://user-images.githubusercontent.com/21986859/99202483-352b8b80-27a7-11eb-8479-8749e945a81d.png) - -### Étape 3: Copier les fichiers de configuration vers les pairs - -Copier chacun des fichiers de configuration vers les pairs correspondants. - -![image](https://user-images.githubusercontent.com/21986859/99201225-e4fdfa80-27a1-11eb-9b27-6e684d30b784.png) - -### Étape 4: Démarrer les services WireGuard - -Démarrez les interfaces WireGuard en utilisant la commande `wg-quick`. Il est également possible de contrôler les interfaces WireGuard via le service système `wg-quick@` de WireGuard. L'état WireGuard peut être vérifié via la commande `wg` après la configuration des interfaces WireGuard. - -![image](https://user-images.githubusercontent.com/21986859/99202554-7459dc80-27a7-11eb-9e92-44cd02bdc2f7.png) - -### Étape 5 : Vérifier la connectivité - -Vérifiez que tous les "endpoints" ont été configurés correctement et peuvent se connecter. - -![image](https://user-images.githubusercontent.com/21986859/99202822-5e98e700-27a8-11eb-8bb2-3e0d2222258f.png) - -C'est fait. Maintenant, un réseau maillé a été créé entre les quatre serveurs. - -## Mise à jour de l'information par les pairs - -Si vous souhaitez mettre à jour les informations d'un pair, utilisez la commande `updatepeer`. La syntaxe de `updatepeer` est la même que celle de la commande `addpeer`. Au lieu d'ajouter un nouveau pair, cette commande écrase les valeurs dans les entrées existantes. - -Dans l'exemple ci-dessous, supposons que vous souhaitiez mettre à jour l'adresse du point d'arrivée de «tokyo1» et le changer en «tokyo321.com». Utilisez la commande `updatepeer` et spécifiez le nouveau paramètre à être `tokyo321.com`. Cela écrasera la valeur `tokyo1` existante de `Endpoint`. - -![image](https://user-images.githubusercontent.com/21986859/99204025-3a3f0980-27ac-11eb-9159-0e40fc2eefeb.png) - -## Afficher l'information des pairs - -La commande `showpeers` imprime par défaut toutes les informations de pairs. - -![image](https://user-images.githubusercontent.com/21986859/99205966-11ba0e00-27b2-11eb-994a-6d2552ff1ca4.png) - -Maintenant c'est beaucoup d'informations et beaucoup de colonnes inutiles qui n'ont que `None`s. J'ai donc ajouté la commande `-s`/`--simplify` qui omet ces colonnes inutiles. - -![image](https://user-images.githubusercontent.com/21986859/99206017-38784480-27b2-11eb-9022-21ba791ce28c.png) - -Vous pouvez également demander des renseignements sur un pair particulier. - -![image](https://user-images.githubusercontent.com/21986859/99206049-547be600-27b2-11eb-89e9-d7c942dfac44.png) - -Le mode texte simple a une utilisation similaire. C'est un peu plus dur à lire. - -![image](https://user-images.githubusercontent.com/21986859/99206104-76756880-27b2-11eb-844b-e5197afcbf99.png) - -## Suppression des pairs - -Utilisez la commande `delpeer` pour supprimer les pairs. La syntaxe est `delpeer PEER_NAME`. - -Cet exemple ci-dessous montre comment supprimer le pair `tokyo1` de la base de données. - -![image](https://user-images.githubusercontent.com/21986859/99204215-e123a580-27ac-11eb-93b1-d07345004fab.png) - -## Fichiers de base de données - -Toutes les opérations ajout, mise à jour et suppression de pairs sont des opérations de fichiers. Les modifications seront enregistrées dans le fichier de base de données immédiatement. Le fichier de base de données à utiliser peut être spécifié via l'option `-d` ou `--database`. Si aucun fichier de base de données n'est spécifié, `database.csv` sera utilisé. - -```csv -"Name","Address","Endpoint","AllowedIPs","ListenPort","PersistentKeepalive","FwMark","PrivateKey","DNS","MTU","Table","PreUp","PostUp","PreDown","PostDown","SaveConfig" -"tokyo1","10.1.0.1/16","tokyo1.com","","51820","","","yJndNh80ToNWGOfDlbtho1wHAEZGa7ZhNpsHf7AJVUM=","","","","","","","","" -"germany1","10.2.0.1/16","germany1.com","","51820","","","SEOaOjTrhR4do1iUrTTRRHZs6xCA3Q/H0yHW3ZpkHko=","","","","","","","","" -"canada1","10.3.0.1/16","canada1.com","","51820","","","2D34jpbTsU+KeBqfItTEbL5m7nYcBomWWJGTYCT6eko=","","","","","","","","" -"shanghai1","10.4.0.1/16","shanghai1.com","","51820","","","CGyR7goj/uGH3TQHgVknpb9ZBR+/yMfkve+kVNGBYlg=","","","","","","","","" -``` - -## Utilisations détaillées - -Vous pouvez consulter la page d'aide du programme. Utilisez le commutateur `-h` ou `--help` pour imprimer la page d'aide. - -```shell -$ wg-meshconf -h -usage: wg-meshconf [-h] [-d DATABASE] {addpeer,updatepeer,delpeer,showpeers,genconfig} ... - -positional arguments: - {addpeer,updatepeer,delpeer,showpeers,genconfig} - -optional arguments: - -h, --help show this help message and exit - -d DATABASE, --database DATABASE - path where the database file is stored (default: database.json) -``` - -Spécifiez `-h` ou `--help` après une commande pour voir les différentes utilisations de cette commande. - -```shell -$ wg-meshconf addpeer -h -usage: wg-meshconf addpeer [-h] --address ADDRESS [--endpoint ENDPOINT] [--privatekey PRIVATEKEY] [--listenport LISTENPORT] [--fwmark FWMARK] [--dns DNS] [--mtu MTU] [--table TABLE] [--preup PREUP] [--postup POSTUP] [--predown PREDOWN] [--postdown POSTDOWN] [--saveconfig] name - -positional arguments: - name Name used to identify this node - -optional arguments: - -h, --help show this help message and exit - --address ADDRESS address of the server - --endpoint ENDPOINT peer's public endpoint address - --privatekey PRIVATEKEY - private key of server interface - --listenport LISTENPORT - port to listen on - --fwmark FWMARK fwmark for outgoing packets - --dns DNS server interface DNS servers - --mtu MTU server interface MTU - --table TABLE server routing table - --preup PREUP command to run before interface is up - --postup POSTUP command to run after interface is up - --predown PREDOWN command to run before interface is down - --postdown POSTDOWN command to run after interface is down - --saveconfig save server interface to config upon shutdown -``` - -## License - -Ce projet est sous licence [GNU General Public License Version 3 (GNU GPL v3)](https://www.gnu.org/licenses/gpl-3.0.txt)\ -Copyright (c) 2018-2023 K4YT3X and contributors. - -![GPLv3 Icon](https://www.gnu.org/graphics/gplv3-127x51.png) - -Ce projet comprend ou dépend des logiciels et projets suivants: - -| **Project** | **License** | -| ---------------------------------------------------- | ----------- | -| [Rich](https://github.com/Textualize/rich) | MIT License | -| [WireGuard](https://git.zx2c4.com/wireguard) | MIT License | -| [cryptography](https://github.com/pyca/cryptography) | BSD License | - diff --git a/README.md b/README.md index 0059f7e..8a9581f 100644 --- a/README.md +++ b/README.md @@ -1,178 +1,179 @@ # wg-meshconf -wg-meshconf is a tool that will help you to generate peer configuration files for WireGuard mesh networks. You can easily and quickly create WireGuard mesh networks using this tool. +wg-meshconf est un outil qui vous aidera à générer des fichiers de configuration par les pairs pour les réseaux de mailles WireGuard. Vous pouvez facilement et rapidement créer des réseaux de mailles WireGuard à l'aide de cet outil. -## Installation (PyPI) +## Installation (pipx) -**This is the recommended way to install wg-meshconf for regular users.** This installation method installs the newest release version of wg-meshconf and all of the required dependencies from PyPI. +Installer Pipx sous Linux ```shell -# installing the program with pip -# note that Pip for Python3 might be named "pip3" on some systems -pip install --user -U wg-meshconf +python -S python-pipx +``` + +Avoir le bon chemein + +```shell +pipx ensurepath +``` + +Résultat commande + +``` +Success! Added /home/yann/.local/bin to the PATH environment variable. + +Consider adding shell completions for pipx. Run 'pipx completions' for instructions. + +You will need to open a new terminal or re-login for the PATH changes to take effect. +Alternatively, you can source your shell's config file with e.g. 'source ~/.bashrc'. + +Otherwise pipx is ready to go! ✨ 🌟 ✨ +``` + +Rafraîchir pour prise en compte de la modification du chemin (path) + +```shell +source ~/.bashrc +``` + +**pipx, est la façon recommandée d'installer wg-meshconf pour les utilisateurs réguliers**. Cette méthode d'installation installe la dernière version de version de wg-meshconf et toutes les dépendances requises de PyPI. + +```shell +# installing the program with pipx +pipx install wg-meshconf # running the program wg-meshconf showpeers ``` -You may now run the program by executing the `wg-meshconf` command. +## Apprendre par un exemple -## Installation (GitHub) +Voyons un exemple réel de la façon dont cet outil peut être utilisé. Cette section montrera comment créer un réseau de mailles simple avec quatre nœuds en utilisant wg-meshconf. -Alternatively, if you would like to install the program directly from source code, you can follow the steps below. If you would like to install directly from the Git repository: - -```shell -# install the HEAD (latest) commit -pip install 'wg-meshconf@git+https://github.com/k4yt3x/wg-meshconf.git' - -# install from a specific tag or commit -pip install 'wg-meshconf@git+https://github.com/k4yt3x/wg-meshconf.git@2.5.1' -pip install 'wg-meshconf@git+https://github.com/k4yt3x/wg-meshconf.git@aa16407' -``` - -You can also clone it and install it locally. - -```shell -# cloning the repository with git -git clone https://github.com/k4yt3x/wg-meshconf.git - -# enter the directory -cd wg-meshconf - -# install the program with Pip -# Pip and PDM will take care of dependency installation -pip install -U . -``` - -## Learn by an Example - -Usages are dull and boring. Let's see a real-life example of how this tool can be used. This section will demonstrate how to create a simple mesh network with four nodes using wg-meshconf. - -For this example, suppose you have four servers as shown below. These servers can reach each other via the `Endpoint` address. For instance, server `tokyo1` can ping server `shanghai1` with the address `shanghai1.com`. +Pour cet exemple, supposons que vous ayez quatre serveurs comme indiqué ci-dessous. Ces serveurs peuvent se rejoindre par l'adresse `Endpoint`. Par exemple, le serveur `tokyo1` peut ping server `shanghai1` avec l'adresse `shanghai1.com`. ![image](https://user-images.githubusercontent.com/21986859/99200153-94839e80-279b-11eb-81c9-189b609661ee.png) -### Step 1: Add Basic Peer Information +### Étape 1 : Ajouter la base Information Pair (Peer) -You will first need to add the peers' information into the database. There are two ways to do it: via Excel and via the command line interface. +Vous devrez d'abord ajouter l'information des pairs dans la base de données. +Il y a deux façons de le faire : -#### Method A: With Excel +* via Excel +* via l'interface de ligne de commande. -wg-meshconf has changed its database format from JSON to CSV and added the `init` command since version 2.4.0. This means that it is now possible for users to directly edit the database file with Excel or other CSV-compatible editors to create/read/update/delete peer information. +#### Méthode A: Avec Excel -> (P.S. I thought about making a fancy GUI for wg-meshconf like the other tools, but then I thought, why do it the complex way when you can simply "borrow" Excel's GUI?) +wg-meshconf a changé son format de base de données de JSON à CSV et a ajouté la commande `init` depuis la version 2.4.0. Cela signifie qu'il est maintenant possible pour les utilisateurs de modifier directement le fichier de base de données avec Excel ou d'autres éditeurs compatibles CSV pour créer/lire/update/effacer l'information des pairs. -Run the following command to initialize a new database file. By default, the database file is named `database.csv`. You can also specify the file's name via `-d`. +Exécutez la commande suivante pour initialiser un nouveau fichier de base de données. Par défaut, le fichier de base de données est nommé `database.csv`. Vous pouvez également spécifier le nom du fichier via `-d`. ```shell wg-meshconf init ``` -Open the database CSV file with an editor like Excel or LibreOffice Calc. You should see the following column headers. +Ouvrez le fichier CSV avec un éditeur comme Excel ou LibreOffice Calc. Vous devriez voir les en-têtes de colonne suivantes. ![image](https://user-images.githubusercontent.com/21986859/120080963-93b4b900-c0aa-11eb-9e40-0da767c1cbfc.png) -You can then fill in the peers' information. **You will need to fill in at least the peers' `Name`, `Address`, and `Endpoint` values.** These values cannot be automatically generated. +Vous pouvez ensuite remplir l'information des pairs. **Vous devrez remplir au moins les valeurs `Nom`, `Adresse` et `Endpoint` des pairs.** Ces valeurs ne peuvent pas être générées automatiquement. ![image](https://user-images.githubusercontent.com/21986859/120081082-2fdec000-c0ab-11eb-90ad-0993a0557e1e.png) -Once you're done, save the file and execute the `init` command again to automatically generate the rest of the needed information such as peer private keys. +Une fois que vous avez terminé, enregistrez le fichier et exécutez à nouveau la commande `init` pour générer automatiquement le reste des informations nécessaires telles que les clés privées de pair. ```shell wg-meshconf init ``` -If you check the file again, you'll see the necessary fields getting automatically filed in. +Si vous vérifiez à nouveau le fichier, vous verrez les champs nécessaires se déposer automatiquement. ![image](https://user-images.githubusercontent.com/21986859/120081172-a2e83680-c0ab-11eb-963d-b6810a6580a3.png) -#### Method B: With Terminal +#### Méthode B: Avec terminal -If, for some reason, you don't want to edit the database file directly, you can also use this tool purely through its command line interface. +Si, pour une raison quelconque, vous ne voulez pas modifier le fichier de base de données directement, vous pouvez également utiliser cet outil uniquement via son interface en ligne de commande. -First we need to add all peers in the mesh network into the database. The basic syntax for adding new peers is: +D'abord, nous devons ajouter tous les pairs du réseau de maillé dans la base de données. La syntaxe de base pour ajouter de nouveaux pairs est : ```shell wg-meshconf addpeer NAME --address IP_ADDRESS --address IP_ADDRESS_2 --endpoint ENDPOINT ``` -- New private key will be generated automatically if unspecified -- ListenPort defaults to 51820 per WireGuard standard -- All other values are left empty by default +- Une nouvelle clé privée sera générée automatiquement si non spécifiée +- ListenPort par défaut à 51820 , standard WireGuard +- Toutes les autres valeurs restent vides par défaut -There are more options which you can specify. Use the command `wg-meshconf addpeer -h` for more details. +Il y a d'autres options que vous pouvez spécifier. Utilisez la commande `wg-meshconf addpeer -h` pour plus de détails. -After adding all the peers into the database, you can verify that they have all been added correctly via the `wg-meshconf showpeers` command. The `simplify` switch here omits all columns with only `None`s. +Après avoir ajouté tous les pairs dans la base de données, vous pouvez vérifier qu'ils ont tous été ajoutés correctement via la commande `wg-meshconf showpeers`. Le commutateur `simplify` omet ici toutes les colonnes avec seulement `None`s. ![image](https://user-images.githubusercontent.com/21986859/99202459-1dec9e00-27a7-11eb-8190-a5a3c6644d2a.png) -### Step 2: Export Configuration Files +### Étape 2: Exporter les fichiers de configuration -Use the `genconfig` command to generate configuration files for all peers. You may also export configurations for only one peer by specifying the peer's name. +Utilisez la commande `genconfig` pour générer des fichiers de configuration pour tous les pairs. Vous pouvez également exporter des configurations pour un seul pair en spécifiant le nom du pair. -The configuration files will be named after the peers' names. By default, all configuration files are exported into a subdirectory named `output`. You can change this by specifying output directory using the `-o` or the `--output` option. +Les fichiers de configuration seront nommés d'après les noms des pairs. Par défaut, tous les fichiers de configuration sont exportés dans un sous-répertoire nommé `output`. Vous pouvez modifier cela en spécifiant le répertoire de sortie en utilisant l'option `-o` ou `--output`. ![image](https://user-images.githubusercontent.com/21986859/99202483-352b8b80-27a7-11eb-8479-8749e945a81d.png) -### Step 3: Copy Configuration Files to Peers +### Étape 3: Copier les fichiers de configuration vers les pairs -Copy each of the configuration files to the corresponding peers. +Copier chacun des fichiers de configuration vers les pairs correspondants. ![image](https://user-images.githubusercontent.com/21986859/99201225-e4fdfa80-27a1-11eb-9b27-6e684d30b784.png) -### Step 4: Start WireGuard Services +### Étape 4: Démarrer les services WireGuard -Start up the WireGuard interfaces using the `wg-quick` command. It is also possible to control WireGuard interfaces via WireGuard's `wg-quick@` systemd service. WireGuard status can be verified via the `wg` command after WireGuard interfaces are set up. +Démarrez les interfaces WireGuard en utilisant la commande `wg-quick`. Il est également possible de contrôler les interfaces WireGuard via le service système `wg-quick@` de WireGuard. L'état WireGuard peut être vérifié via la commande `wg` après la configuration des interfaces WireGuard. ![image](https://user-images.githubusercontent.com/21986859/99202554-7459dc80-27a7-11eb-9e92-44cd02bdc2f7.png) -### Step 5: Verify Connectivity +### Étape 5 : Vérifier la connectivité -Verify that all endpoints have been configured properly and can connect to each other. +Vérifiez que tous les "endpoints" ont été configurés correctement et peuvent se connecter. ![image](https://user-images.githubusercontent.com/21986859/99202822-5e98e700-27a8-11eb-8bb2-3e0d2222258f.png) -Done. Now a mesh network has been created between the four servers. +C'est fait. Maintenant, un réseau maillé a été créé entre les quatre serveurs. -## Updating Peer Information +## Mise à jour de l'information par les pairs -If you would like to update a peer's information, use the `updatepeer` command. The syntax of `updatepeer` is the same as that of the `addpeer` command. Instead of adding a new peer, this command overwrites values in existing entries. +Si vous souhaitez mettre à jour les informations d'un pair, utilisez la commande `updatepeer`. La syntaxe de `updatepeer` est la même que celle de la commande `addpeer`. Au lieu d'ajouter un nouveau pair, cette commande écrase les valeurs dans les entrées existantes. -In the example below, suppose you would like to update `tokyo1`'s endpoint address and change it to `tokyo321.com`. Use the `updatepeer` command and specify the new endpoint to be `tokyo321.com`. This will overwrite `tokyo1`'s existing `Endpoint` value. +Dans l'exemple ci-dessous, supposons que vous souhaitiez mettre à jour l'adresse du point d'arrivée de «tokyo1» et le changer en «tokyo321.com». Utilisez la commande `updatepeer` et spécifiez le nouveau paramètre à être `tokyo321.com`. Cela écrasera la valeur `tokyo1` existante de `Endpoint`. ![image](https://user-images.githubusercontent.com/21986859/99204025-3a3f0980-27ac-11eb-9159-0e40fc2eefeb.png) -## Show Peer Information +## Afficher l'information des pairs -The `showpeers` command prints all peers' information by default. +La commande `showpeers` imprime par défaut toutes les informations de pairs. ![image](https://user-images.githubusercontent.com/21986859/99205966-11ba0e00-27b2-11eb-994a-6d2552ff1ca4.png) -Now that's a lot of info and a lot of unnecessary columns which only have `None`s. Therefore, I added the `-s`/`--simplify` command which omits those useless columns. +Maintenant c'est beaucoup d'informations et beaucoup de colonnes inutiles qui n'ont que `None`s. J'ai donc ajouté la commande `-s`/`--simplify` qui omet ces colonnes inutiles. ![image](https://user-images.githubusercontent.com/21986859/99206017-38784480-27b2-11eb-9022-21ba791ce28c.png) -You may also query information about a specific peer. +Vous pouvez également demander des renseignements sur un pair particulier. ![image](https://user-images.githubusercontent.com/21986859/99206049-547be600-27b2-11eb-89e9-d7c942dfac44.png) -Plaintext mode has a similar usage. It's just a bit harder to read, at least for me. +Le mode texte simple a une utilisation similaire. C'est un peu plus dur à lire. ![image](https://user-images.githubusercontent.com/21986859/99206104-76756880-27b2-11eb-844b-e5197afcbf99.png) -## Deleting Peers +## Suppression des pairs -Use the `delpeer` command to delete peers. The syntax is `delpeer PEER_NAME`. +Utilisez la commande `delpeer` pour supprimer les pairs. La syntaxe est `delpeer PEER_NAME`. -This example below shows how to delete the peer `tokyo1` from the database. +Cet exemple ci-dessous montre comment supprimer le pair `tokyo1` de la base de données. ![image](https://user-images.githubusercontent.com/21986859/99204215-e123a580-27ac-11eb-93b1-d07345004fab.png) -## Database Files +## Fichiers de base de données -Unlike 1.x.x versions of wg-meshconf, version 2.0.0 does not require the user to save or load profiles. Instead, all add peer, update peer and delete peer operations are file operations. The changes will be saved to the database file immediately. The database file to use can be specified via the `-d` or the `--database` option. If no database file is specified, `database.csv` will be used. - -Database files are essentially just CSV files (it was JSON before version 2.4.0). Below is an example. +Toutes les opérations ajout, mise à jour et suppression de pairs sont des opérations de fichiers. Les modifications seront enregistrées dans le fichier de base de données immédiatement. Le fichier de base de données à utiliser peut être spécifié via l'option `-d` ou `--database`. Si aucun fichier de base de données n'est spécifié, `database.csv` sera utilisé. ```csv "Name","Address","Endpoint","AllowedIPs","ListenPort","PersistentKeepalive","FwMark","PrivateKey","DNS","MTU","Table","PreUp","PostUp","PreDown","PostDown","SaveConfig" @@ -182,9 +183,9 @@ Database files are essentially just CSV files (it was JSON before version 2.4.0) "shanghai1","10.4.0.1/16","shanghai1.com","","51820","","","CGyR7goj/uGH3TQHgVknpb9ZBR+/yMfkve+kVNGBYlg=","","","","","","","","" ``` -## Detailed Usages +## Utilisations détaillées -You may refer to the program's help page for usages. Use the `-h` switch or the `--help` switch to print the help page. +Vous pouvez consulter la page d'aide du programme. Utilisez le commutateur `-h` ou `--help` pour imprimer la page d'aide. ```shell $ wg-meshconf -h @@ -199,7 +200,7 @@ optional arguments: path where the database file is stored (default: database.json) ``` -Specify `-h` or `--help` after a command to see this command's usages. +Spécifiez `-h` ou `--help` après une commande pour voir les différentes utilisations de cette commande. ```shell $ wg-meshconf addpeer -h @@ -229,12 +230,12 @@ optional arguments: ## License -This project is licensed under the [GNU General Public License Version 3 (GNU GPL v3)](https://www.gnu.org/licenses/gpl-3.0.txt)\ +Ce projet est sous licence [GNU General Public License Version 3 (GNU GPL v3)](https://www.gnu.org/licenses/gpl-3.0.txt)\ Copyright (c) 2018-2023 K4YT3X and contributors. ![GPLv3 Icon](https://www.gnu.org/graphics/gplv3-127x51.png) -This project includes or dependson the following software and projects: +Ce projet comprend ou dépend des logiciels et projets suivants: | **Project** | **License** | | ---------------------------------------------------- | ----------- | @@ -242,8 +243,3 @@ This project includes or dependson the following software and projects: | [WireGuard](https://git.zx2c4.com/wireguard) | MIT License | | [cryptography](https://github.com/pyca/cryptography) | BSD License | -## Related Project: `wg-dynamic` - -`wg-dynamic` is a tool designed officially by the WireGuard developing team. This new utility will provide a convenient way of configuring networks dynamically, where mesh network being one of the them. If you're interested, check it out at [wg-dynamic@github](https://github.com/WireGuard/wg-dynamic) or [wg-dynamic@official repository](https://git.zx2c4.com/wg-dynamic). You might also want to read this project's [idea page](https://github.com/WireGuard/wg-dynamic/blob/master/docs/idea.md). - -This section used to be on the top of the page, but has been moved since there has been no new commits observed in this project since 2019. diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..0059f7e --- /dev/null +++ b/README_EN.md @@ -0,0 +1,249 @@ +# wg-meshconf + +wg-meshconf is a tool that will help you to generate peer configuration files for WireGuard mesh networks. You can easily and quickly create WireGuard mesh networks using this tool. + +## Installation (PyPI) + +**This is the recommended way to install wg-meshconf for regular users.** This installation method installs the newest release version of wg-meshconf and all of the required dependencies from PyPI. + +```shell +# installing the program with pip +# note that Pip for Python3 might be named "pip3" on some systems +pip install --user -U wg-meshconf + +# running the program +wg-meshconf showpeers +``` + +You may now run the program by executing the `wg-meshconf` command. + +## Installation (GitHub) + +Alternatively, if you would like to install the program directly from source code, you can follow the steps below. If you would like to install directly from the Git repository: + +```shell +# install the HEAD (latest) commit +pip install 'wg-meshconf@git+https://github.com/k4yt3x/wg-meshconf.git' + +# install from a specific tag or commit +pip install 'wg-meshconf@git+https://github.com/k4yt3x/wg-meshconf.git@2.5.1' +pip install 'wg-meshconf@git+https://github.com/k4yt3x/wg-meshconf.git@aa16407' +``` + +You can also clone it and install it locally. + +```shell +# cloning the repository with git +git clone https://github.com/k4yt3x/wg-meshconf.git + +# enter the directory +cd wg-meshconf + +# install the program with Pip +# Pip and PDM will take care of dependency installation +pip install -U . +``` + +## Learn by an Example + +Usages are dull and boring. Let's see a real-life example of how this tool can be used. This section will demonstrate how to create a simple mesh network with four nodes using wg-meshconf. + +For this example, suppose you have four servers as shown below. These servers can reach each other via the `Endpoint` address. For instance, server `tokyo1` can ping server `shanghai1` with the address `shanghai1.com`. + +![image](https://user-images.githubusercontent.com/21986859/99200153-94839e80-279b-11eb-81c9-189b609661ee.png) + +### Step 1: Add Basic Peer Information + +You will first need to add the peers' information into the database. There are two ways to do it: via Excel and via the command line interface. + +#### Method A: With Excel + +wg-meshconf has changed its database format from JSON to CSV and added the `init` command since version 2.4.0. This means that it is now possible for users to directly edit the database file with Excel or other CSV-compatible editors to create/read/update/delete peer information. + +> (P.S. I thought about making a fancy GUI for wg-meshconf like the other tools, but then I thought, why do it the complex way when you can simply "borrow" Excel's GUI?) + +Run the following command to initialize a new database file. By default, the database file is named `database.csv`. You can also specify the file's name via `-d`. + +```shell +wg-meshconf init +``` + +Open the database CSV file with an editor like Excel or LibreOffice Calc. You should see the following column headers. + +![image](https://user-images.githubusercontent.com/21986859/120080963-93b4b900-c0aa-11eb-9e40-0da767c1cbfc.png) + +You can then fill in the peers' information. **You will need to fill in at least the peers' `Name`, `Address`, and `Endpoint` values.** These values cannot be automatically generated. + +![image](https://user-images.githubusercontent.com/21986859/120081082-2fdec000-c0ab-11eb-90ad-0993a0557e1e.png) + +Once you're done, save the file and execute the `init` command again to automatically generate the rest of the needed information such as peer private keys. + +```shell +wg-meshconf init +``` + +If you check the file again, you'll see the necessary fields getting automatically filed in. + +![image](https://user-images.githubusercontent.com/21986859/120081172-a2e83680-c0ab-11eb-963d-b6810a6580a3.png) + +#### Method B: With Terminal + +If, for some reason, you don't want to edit the database file directly, you can also use this tool purely through its command line interface. + +First we need to add all peers in the mesh network into the database. The basic syntax for adding new peers is: + +```shell +wg-meshconf addpeer NAME --address IP_ADDRESS --address IP_ADDRESS_2 --endpoint ENDPOINT +``` + +- New private key will be generated automatically if unspecified +- ListenPort defaults to 51820 per WireGuard standard +- All other values are left empty by default + +There are more options which you can specify. Use the command `wg-meshconf addpeer -h` for more details. + +After adding all the peers into the database, you can verify that they have all been added correctly via the `wg-meshconf showpeers` command. The `simplify` switch here omits all columns with only `None`s. + +![image](https://user-images.githubusercontent.com/21986859/99202459-1dec9e00-27a7-11eb-8190-a5a3c6644d2a.png) + +### Step 2: Export Configuration Files + +Use the `genconfig` command to generate configuration files for all peers. You may also export configurations for only one peer by specifying the peer's name. + +The configuration files will be named after the peers' names. By default, all configuration files are exported into a subdirectory named `output`. You can change this by specifying output directory using the `-o` or the `--output` option. + +![image](https://user-images.githubusercontent.com/21986859/99202483-352b8b80-27a7-11eb-8479-8749e945a81d.png) + +### Step 3: Copy Configuration Files to Peers + +Copy each of the configuration files to the corresponding peers. + +![image](https://user-images.githubusercontent.com/21986859/99201225-e4fdfa80-27a1-11eb-9b27-6e684d30b784.png) + +### Step 4: Start WireGuard Services + +Start up the WireGuard interfaces using the `wg-quick` command. It is also possible to control WireGuard interfaces via WireGuard's `wg-quick@` systemd service. WireGuard status can be verified via the `wg` command after WireGuard interfaces are set up. + +![image](https://user-images.githubusercontent.com/21986859/99202554-7459dc80-27a7-11eb-9e92-44cd02bdc2f7.png) + +### Step 5: Verify Connectivity + +Verify that all endpoints have been configured properly and can connect to each other. + +![image](https://user-images.githubusercontent.com/21986859/99202822-5e98e700-27a8-11eb-8bb2-3e0d2222258f.png) + +Done. Now a mesh network has been created between the four servers. + +## Updating Peer Information + +If you would like to update a peer's information, use the `updatepeer` command. The syntax of `updatepeer` is the same as that of the `addpeer` command. Instead of adding a new peer, this command overwrites values in existing entries. + +In the example below, suppose you would like to update `tokyo1`'s endpoint address and change it to `tokyo321.com`. Use the `updatepeer` command and specify the new endpoint to be `tokyo321.com`. This will overwrite `tokyo1`'s existing `Endpoint` value. + +![image](https://user-images.githubusercontent.com/21986859/99204025-3a3f0980-27ac-11eb-9159-0e40fc2eefeb.png) + +## Show Peer Information + +The `showpeers` command prints all peers' information by default. + +![image](https://user-images.githubusercontent.com/21986859/99205966-11ba0e00-27b2-11eb-994a-6d2552ff1ca4.png) + +Now that's a lot of info and a lot of unnecessary columns which only have `None`s. Therefore, I added the `-s`/`--simplify` command which omits those useless columns. + +![image](https://user-images.githubusercontent.com/21986859/99206017-38784480-27b2-11eb-9022-21ba791ce28c.png) + +You may also query information about a specific peer. + +![image](https://user-images.githubusercontent.com/21986859/99206049-547be600-27b2-11eb-89e9-d7c942dfac44.png) + +Plaintext mode has a similar usage. It's just a bit harder to read, at least for me. + +![image](https://user-images.githubusercontent.com/21986859/99206104-76756880-27b2-11eb-844b-e5197afcbf99.png) + +## Deleting Peers + +Use the `delpeer` command to delete peers. The syntax is `delpeer PEER_NAME`. + +This example below shows how to delete the peer `tokyo1` from the database. + +![image](https://user-images.githubusercontent.com/21986859/99204215-e123a580-27ac-11eb-93b1-d07345004fab.png) + +## Database Files + +Unlike 1.x.x versions of wg-meshconf, version 2.0.0 does not require the user to save or load profiles. Instead, all add peer, update peer and delete peer operations are file operations. The changes will be saved to the database file immediately. The database file to use can be specified via the `-d` or the `--database` option. If no database file is specified, `database.csv` will be used. + +Database files are essentially just CSV files (it was JSON before version 2.4.0). Below is an example. + +```csv +"Name","Address","Endpoint","AllowedIPs","ListenPort","PersistentKeepalive","FwMark","PrivateKey","DNS","MTU","Table","PreUp","PostUp","PreDown","PostDown","SaveConfig" +"tokyo1","10.1.0.1/16","tokyo1.com","","51820","","","yJndNh80ToNWGOfDlbtho1wHAEZGa7ZhNpsHf7AJVUM=","","","","","","","","" +"germany1","10.2.0.1/16","germany1.com","","51820","","","SEOaOjTrhR4do1iUrTTRRHZs6xCA3Q/H0yHW3ZpkHko=","","","","","","","","" +"canada1","10.3.0.1/16","canada1.com","","51820","","","2D34jpbTsU+KeBqfItTEbL5m7nYcBomWWJGTYCT6eko=","","","","","","","","" +"shanghai1","10.4.0.1/16","shanghai1.com","","51820","","","CGyR7goj/uGH3TQHgVknpb9ZBR+/yMfkve+kVNGBYlg=","","","","","","","","" +``` + +## Detailed Usages + +You may refer to the program's help page for usages. Use the `-h` switch or the `--help` switch to print the help page. + +```shell +$ wg-meshconf -h +usage: wg-meshconf [-h] [-d DATABASE] {addpeer,updatepeer,delpeer,showpeers,genconfig} ... + +positional arguments: + {addpeer,updatepeer,delpeer,showpeers,genconfig} + +optional arguments: + -h, --help show this help message and exit + -d DATABASE, --database DATABASE + path where the database file is stored (default: database.json) +``` + +Specify `-h` or `--help` after a command to see this command's usages. + +```shell +$ wg-meshconf addpeer -h +usage: wg-meshconf addpeer [-h] --address ADDRESS [--endpoint ENDPOINT] [--privatekey PRIVATEKEY] [--listenport LISTENPORT] [--fwmark FWMARK] [--dns DNS] [--mtu MTU] [--table TABLE] [--preup PREUP] [--postup POSTUP] [--predown PREDOWN] [--postdown POSTDOWN] [--saveconfig] name + +positional arguments: + name Name used to identify this node + +optional arguments: + -h, --help show this help message and exit + --address ADDRESS address of the server + --endpoint ENDPOINT peer's public endpoint address + --privatekey PRIVATEKEY + private key of server interface + --listenport LISTENPORT + port to listen on + --fwmark FWMARK fwmark for outgoing packets + --dns DNS server interface DNS servers + --mtu MTU server interface MTU + --table TABLE server routing table + --preup PREUP command to run before interface is up + --postup POSTUP command to run after interface is up + --predown PREDOWN command to run before interface is down + --postdown POSTDOWN command to run after interface is down + --saveconfig save server interface to config upon shutdown +``` + +## License + +This project is licensed under the [GNU General Public License Version 3 (GNU GPL v3)](https://www.gnu.org/licenses/gpl-3.0.txt)\ +Copyright (c) 2018-2023 K4YT3X and contributors. + +![GPLv3 Icon](https://www.gnu.org/graphics/gplv3-127x51.png) + +This project includes or dependson the following software and projects: + +| **Project** | **License** | +| ---------------------------------------------------- | ----------- | +| [Rich](https://github.com/Textualize/rich) | MIT License | +| [WireGuard](https://git.zx2c4.com/wireguard) | MIT License | +| [cryptography](https://github.com/pyca/cryptography) | BSD License | + +## Related Project: `wg-dynamic` + +`wg-dynamic` is a tool designed officially by the WireGuard developing team. This new utility will provide a convenient way of configuring networks dynamically, where mesh network being one of the them. If you're interested, check it out at [wg-dynamic@github](https://github.com/WireGuard/wg-dynamic) or [wg-dynamic@official repository](https://git.zx2c4.com/wg-dynamic). You might also want to read this project's [idea page](https://github.com/WireGuard/wg-dynamic/blob/master/docs/idea.md). + +This section used to be on the top of the page, but has been moved since there has been no new commits observed in this project since 2019.