From 09f036b3aee79d5a5357ef670924ab49de0378dd Mon Sep 17 00:00:00 2001 From: Guus Sliepen Date: Sat, 28 May 2022 23:12:52 +0200 Subject: [PATCH] Reflow all Markdown files. Use MarkFlow to reflow the Markdown files so they can be read as a text file in a 80-column terminal. Also convert all code blocks into fenced code blocks with a language header, and remove the prompt character; this allows viewers to do syntax highlighting, and allows a human reading the files using a text viewer to simply copy&paste the commands. --- .ci/README.md | 4 +- INSTALL.md | 197 +++++++++++++++++++++++++++++++------------------- QUICKSTART.md | 109 ++++++++++++++-------------- README.md | 39 +++++----- SECURITY.md | 8 +- 5 files changed, 201 insertions(+), 156 deletions(-) diff --git a/.ci/README.md b/.ci/README.md index 3b7f081b..04584139 100644 --- a/.ci/README.md +++ b/.ci/README.md @@ -1,6 +1,6 @@ # Continuous Integration -This directory contains scripts and other files used by the continuous integration system. +This directory contains scripts and other files used by the continuous +integration system. You probably should not run them manually. - diff --git a/INSTALL.md b/INSTALL.md index 4ba0bffd..8f25e045 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,26 +2,30 @@ ## Required -Before you can start compiling tinc from a fresh git clone, you have -to install the very latest versions of the following packages: +Before you can start compiling tinc from a fresh git clone, you have to install +the very latest versions of the following packages: - `meson` or `muon` (read below) - `ninja` or `samurai` - `pkgconf` or `pkg-config` -- `GCC` or `Clang` (any version with C11 support, although older versions might work) -- `OpenSSL`\* (1.1.0+) or `LibreSSL` or `libgcrypt` (not needed if legacy protocol is disabled) +- `GCC` or `Clang` (any version with C11 support, although older versions might + work) +- `OpenSSL`\* (1.1.0+) or `LibreSSL` or `libgcrypt` (not needed if legacy + protocol is disabled) ### No Python? -If you're on a constrained system that doesn't have (or cannot run) Python, you can try building tinc with [muon][muon], -which is a pure C reimplementation of the same idea. -Please note that `meson` is considered to be the main way of building tinc, and `muon` is supported on a best-effort basis. +If you're on a constrained system that doesn't have (or cannot run) Python, you +can try building tinc with [muon][muon], which is a pure C reimplementation of +the same idea. Please note that `meson` is considered to be the main way of +building tinc, and `muon` is supported on a best-effort basis. [muon]: https://git.sr.ht/~lattis/muon ## Optional -Plus a few optional dependencies. Support for them will be enabled if they're present: +Plus a few optional dependencies. Support for them will be enabled if they're +present: - `ncurses` or `PDCurses` - `readline` @@ -29,14 +33,16 @@ Plus a few optional dependencies. Support for them will be enabled if they're pr - `LZO`\* - `LZ4`\* -If packages marked by `*` are not available, tinc will fall back to its own vendored copies. -This behavior can be disabled by setting the appropriate meson option to `disabled`. +If packages marked by `*` are not available, tinc will fall back to its own +vendored copies. This behavior can be disabled by setting the appropriate meson +option to `disabled`. To build `info` documentation you'll also need these packages: - `texinfo` or `makeinfo` -You might also need some additional command-line utilities to be able to run the integration test suite: +You might also need some additional command-line utilities to be able to run the +integration test suite: - `diffutils` - `procps` @@ -47,15 +53,15 @@ Please consult your operating system's documentation for more details. ## Windows -You can build tinc using either the native [Windows SDK][sdk-ms] (which comes with Visual Studio), -or with the Unix-like [msys2 environment][sdk-msys2]. Install either one of them, plus -the latest version of [meson][meson-release]. +You can build tinc using either the native [Windows SDK][sdk-ms] (which comes +with Visual Studio), or with the Unix-like [msys2 environment][sdk-msys2]. +Install either one of them, plus the latest version of [meson][meson-release]. -If you prefer the native SDK, you might want to work on tinc (or build it) under Visual Studio. -To do so, follow [these instructions][meson-vs]. +If you prefer the native SDK, you might want to work on tinc (or build it) under +Visual Studio. To do so, follow [these instructions][meson-vs]. -By default, tinc produces a static Windows build, so you don't need to install anything -in order to _run_ the compiled binaries. +By default, tinc produces a static Windows build, so you don't need to install +anything in order to _run_ the compiled binaries. [sdk-ms]: https://visualstudio.com/ [sdk-msys2]: https://msys2.org/ @@ -68,37 +74,52 @@ in order to _run_ the compiled binaries. ### Setup -Tinc's functionality can vary greatly depending on how you configure it. -Have a look at the available options in [`meson_options.txt`](meson_options.txt), or run: +Tinc's functionality can vary greatly depending on how you configure it. Have a +look at the available options in [`meson_options.txt`](meson_options.txt), or +run: - $ meson configure +```sh +meson configure +``` -First you need to create a build directory. If you want the default experience, run: +First you need to create a build directory. If you want the default experience, +run: - $ meson setup builddir +```sh +meson setup builddir +``` -or with configuration options (your shell can probably autocomplete them on `Tab`, try it): +or with configuration options (your shell can probably autocomplete them on +`Tab`, try it): - $ meson setup builddir -Dprefix=/usr/local -Dbuildtype=release +```sh +meson setup builddir -Dprefix=/usr/local -Dbuildtype=release +``` -(For autotools users: this is a rough equivalent of `autoreconf -fsi && ./configure --prefix=/usr/local --with-foobar`). +(For autotools users: this is a rough equivalent of +`autoreconf -fsi && ./configure --prefix=/usr/local --with-foobar`). -This creates a build directory (named `builddir`) with build type set to `release` -(which enables compiler optimizations) and path prefix set to `/usr/local`. +This creates a build directory (named `builddir`) with build type set to +`release` (which enables compiler optimizations) and path prefix set to +`/usr/local`. -Pass any additional options in the same way. Typically, this is not needed: tinc will -autodetect available libraries and adjust its functionality accordingly. +Pass any additional options in the same way. Typically, this is not needed: tinc +will autodetect available libraries and adjust its functionality accordingly. -If you'd like to reconfigure the project after running `setup`, you can either remove -the build directory and start anew, or use: +If you'd like to reconfigure the project after running `setup`, you can either +remove the build directory and start anew, or use: - $ meson configure builddir -Dlzo=disabled -Dlz4=enabled +```sh +meson configure builddir -Dlzo=disabled -Dlz4=enabled +``` ### Compile You then need to build the project: - $ meson compile -C builddir +```sh +meson compile -C builddir +``` (For autotools users: this is an equivalent of `make -j$(nproc)`). @@ -106,7 +127,9 @@ You then need to build the project: You might want to run the test suite to ensure tinc is working correctly: - $ meson test -C builddir +```sh +meson test -C builddir +``` (For autotools users: this is an equivalent of `make -j$(nproc) test`). @@ -114,20 +137,24 @@ You might want to run the test suite to ensure tinc is working correctly: To install tinc to your system, run: - $ meson install -C builddir +```sh +meson install -C builddir +``` (For autotools users: this is an equivalent of `make install`). -Please be aware that this is not the best method of installing software -because it will not be tracked by your operating system's package manager. You -should use packages provided by your operating system, or build your own -(this is a large and complicated topic which is out of the scope of this document). +Please be aware that this is not the best method of installing software because +it will not be tracked by your operating system's package manager. You should +use packages provided by your operating system, or build your own (this is a +large and complicated topic which is out of the scope of this document). ### Uninstall To uninstall tinc, run: - # ninja -C builddir uninstall +```sh +ninja -C builddir uninstall +``` (For autotools users: this is an equivalent of `make uninstall`). @@ -135,34 +162,44 @@ To uninstall tinc, run: ### Linux to Linux -Cross-compilation is easy to do on Debian or its derivatives. -Set `$HOST` to your target architecture and install the cross-compilation toolchain and `-dev` versions of all libraries you'd like to link: +Cross-compilation is easy to do on Debian or its derivatives. Set `$HOST` to +your target architecture and install the cross-compilation toolchain and `-dev` +versions of all libraries you'd like to link: - $ HOST=armhf - $ dpkg --add-architecture $HOST - $ apt update - $ apt install -y crossbuild-essential-$HOST zlib1g-dev:$HOST … +```sh +HOST=armhf +dpkg --add-architecture $HOST +apt update +apt install -y crossbuild-essential-$HOST zlib1g-dev:$HOST … +``` If you'd like to run tests on emulated hardware, install `qemu-user`: - $ apt install -y qemu-user - $ update-binfmts --enable +```sh +apt install -y qemu-user +update-binfmts --enable +``` -Set two environment variables: the C compiler, and pkg-config, and then proceed as usual: +Set two environment variables: the C compiler, and pkg-config, and then proceed +as usual: - $ export CC=arm-linux-gnueabihf-gcc - $ export PKG_CONFIG=arm-linux-gnueabihf-pkg-config - $ meson setup build --cross-file /dev/null +```sh +export CC=arm-linux-gnueabihf-gcc +export PKG_CONFIG=arm-linux-gnueabihf-pkg-config +meson setup build --cross-file /dev/null +``` -or put the names into a [cross file][cross] and pass it to meson: +Or put the names into a [cross file][cross] and pass it to meson: - $ cat >cross-armhf <cross-armhf <, and others. +tinc is Copyright © 1998-2022 Ivo Timmermans, Guus Sliepen , +and others. For a complete list of authors see the [AUTHORS](AUTHORS) file. -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or (at -your option) any later version. See the file COPYING for more details. +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. See the file COPYING for more details. diff --git a/SECURITY.md b/SECURITY.md index f3a2dea3..de93b5d7 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -23,7 +23,7 @@ contacted about a potential vulnerability, we will do the following: Currently we support the 1.0.x and 1.1.x branches of tinc. -| Version | Supported | -| ------- | ---------- | -| 1.1.x | yes | -| 1.0.x | yes | +| Version | Supported | +|---------|-----------| +| 1.1.x | yes | +| 1.0.x | yes | -- 2.20.1