diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile | 177 | ||||
| -rw-r--r-- | doc/source/conf.py | 261 | ||||
| -rw-r--r-- | doc/source/index.rst | 20 | ||||
| -rw-r--r-- | doc/source/manual/cmdline.rst | 97 | ||||
| -rw-r--r-- | doc/source/manual/config.rst | 309 | ||||
| -rw-r--r-- | doc/source/manual/methods.rst | 100 | ||||
| -rw-r--r-- | doc/source/manual/mtu.rst | 30 |
8 files changed, 995 insertions, 0 deletions
@@ -1 +1,2 @@ *~ +/doc/build diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..0438643 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/fastd.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fastd.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/fastd" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fastd" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..09befb5 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,261 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# fastd documentation build configuration file, created by +# sphinx-quickstart on Wed Sep 3 21:57:04 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.mathjax', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'fastd' +copyright = '2014, Matthias Schiffer' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '15' +# The full version, including alpha/beta/rc tags. +release = '15' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'fastddoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'fastd.tex', 'fastd Documentation', + 'Matthias Schiffer', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'fastd', 'fastd Documentation', + ['Matthias Schiffer'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'fastd', 'fastd Documentation', + 'Matthias Schiffer', 'fastd', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..833c469 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,20 @@ +Welcome to fastd's documentation! +================================= + +User manual +----------- + +.. toctree:: + :maxdepth: 2 + + manual/cmdline + manual/config + manual/methods + manual/mtu + + +Developer documentation +----------------------- + +.. toctree:: + :maxdepth: 2 diff --git a/doc/source/manual/cmdline.rst b/doc/source/manual/cmdline.rst new file mode 100644 index 0000000..66211ca --- /dev/null +++ b/doc/source/manual/cmdline.rst @@ -0,0 +1,97 @@ +Command line options +==================== + +Command line options and config files are parsed in order they are specified, so config files specified before other options are overwritten by the other options, config files specified later will overwrite options specified before. + +--help, -h + Shows this help text + +--version, -v + Shows the fastd version + +--daemon, -d + Runs fastd in the background + +--pid-file <filename> + Writes fastd's PID to the specified file. + +--log-level <error|warn|info|verbose|debug|debug2> + Sets the stderr log level; default is info, + if no alternative log destination ist configured. + If logging to syslog or files is enabled, the default is not to log to stderr. + +--syslog-level <error|warn|info|verbose|debug|debug2> + Sets the log level for syslog output; default is not to use syslog. + +--syslog-ident <ident> + Sets the syslog identification; default is 'fastd'. + +--config, -c <filename> + Loads a config file. - can be specified to read a config file from stdin. + +--config-peer <filename> + Loads a config file for a single peer. The filename will be used as the peer name. + +--config-peer-dir <dir> + Loads all files from a directory as peer configs. On SIGHUP fastd will reload peer directories. + +--mode, -m <tap|tun> + Sets the mode of the interface; default is TAP mode. + +--interface, -i <name> + Sets the name of the TUN/TAP interface to use. If not specified, default names specified by the system will be used. + +--mtu, -M <mtu> + Sets the MTU; must be at least 576. You should read MTU configuration, the default 1500 is suboptimal in most setups. + +--bind, -b <address:port> + Sets the bind address. Address can be an IPv4 address or an IPv6 address, or the keyword any. IPv6 addresses must be put in square brackets. + + Default is to bind to a random port, for IPv4 and IPv6. You can specify one IPv4 and one IPv6 bind address, or both at once as any. It is currently + not possible to specify an IPv6 link-local address on the command line. + +--protocol, -p <protocol> + Sets the handshake protocol. Currently the only protocol available is ec25519-fhmqvc, which provides a secure authentication of peers based on public/secret keys. + +--method <method> + Sets the encryption/authentication method. See the page :doc:`methods` for more information about the supported methods. More than one method can be specified; the earlier you specify + a method the higher is the preference for a method, so methods speficied later will only be used if a peer doesn't support the first methods. + +--forward + Enables forwarding of packets between clients; read the paragraph about this option before use! + +--on-pre-up <command> + Sets a shell command to execute before interface creation. See the detailed documentation below for an overview of the available environment variables. + +--on-up <command> + Sets a shell command to execute after interface creation. See the detailed documentation below for an overview of the available environment variables. + +--on-down <command> + Sets a shell command to execute before interface destruction. See the detailed documentation below for an overview of the available environment variables. + +--on-post-down <command> + Sets a shell command to execute after interface destruction. See the detailed documentation below for an overview of the available environment variables. + +--on-connect <command> + Sets a shell command to execute when a handshake is sent to establish a new connection. + +--on-establish <command> + Sets a shell command to execute when a new connection is established. See the detailed documentation below for an overview of the available environment variables. + +--on-disestablish <command> + Sets a shell command to execute when a connection is lost. See the detailed documentation below for an overview of the available environment variables. + +--on-verify <command> + Sets a shell command to execute to check a connection attempt by an unknown peer. See the detailed documentation below for more information and an overview of the available environment variables. + +--verify-config + Checks the configuration and exits. + +--generate-key + Generates a new keypair. + +--show-key + Shows the public key corresponding to the configured secret. + +--machine-readable + Suppresses output of explaining text in the --show-key and --generate-key commands. diff --git a/doc/source/manual/config.rst b/doc/source/manual/config.rst new file mode 100644 index 0000000..ba924e8 --- /dev/null +++ b/doc/source/manual/config.rst @@ -0,0 +1,309 @@ +Configuration file format +========================= + +Main configuration +------------------ + +Example config: + +:: + + # Log warnings and errors to stderr + log level warn; + + # Log everything to syslog + log to syslog level debug; + + # Set the interface name + interface "mesh-vpn"; + + # Support xsalsa20 and aes128 encryption methods, prefer xsalsa20 + method "xsalsa20-poly1305"; + method "aes128-gcm"; + + # Bind to a fixed port, IPv4 only + bind 0.0.0.0:10000; + + # Secret key generated by `fastd --generate-key` + secret "78dfb05fe0aa586fb017de566b0d21398ac64032fcf1c765855f4d538cc5a357"; + + # Set the interface MTU for TAP mode with xsalsa20/aes128 over IPv4 with a base MTU of 1492 (PPPoE) + # (see MTU selection documentation) + mtu 1426; + + # Include peers from the directory 'peers' + include peers from "peers"; + + +| ``bind <IPv4 address>:<port> [ interface "<interface>" ] [ default [ ipv4 ] ];`` +| ``bind <IPv6 address>:<port> [ interface "<interface>" ] [ default [ ipv6 ] ];`` +| ``bind any:<port> [ interface "<interface>" ] [ default [ ipv4|ipv6 ] ];`` +| ``bind <IPv4 address> port <port> [ interface "<interface>" ] [ default [ ipv4 ] ];`` +| ``bind <IPv6 address> port <port> [ interface "<interface>" ] [ default [ ipv6 ] ];`` +| ``bind any port <port> [ interface "<interface>" ] [ default [ ipv4|ipv6 ] ];`` + + Sets the bind address, port and possibly interface. May be specified multiple times. The keyword + any makes fastd bind to the unspecified address for both IPv4 and IPv6. When + no bind address is configured at all, for each outgoing connection a new socket with a random + port is created. + + IPv6 address must be put in square brackets. It is possible to specify an IPv6 link-local address + with an interface in the usual notation (e.g. [fe80::1%eth0]). + + The default option makes it the default address for outgoing connections + for IPv4, IPv6 or both. + + +| ``cipher "<cipher>" use "<implementation>";`` + + Chooses a specific impelemenation for a cipher. Normally, the default setting is already the best choice. + Note that specific implementations may be unavailable on some platforms or disabled during compilation. + The available ciphers and implementations are: + + * ``aes128-ctr``: AES128 in counter mode + + - ``openssl``: Use implementation from OpenSSL's libcrypto + - ``nacl``: Use implementation from NaCl or libsodium + + * ``null``: No encryption (for authenticated-only methods using composed_gmac) + + - ``memcpy``: Simple memcpy-based implementation + + * ``salsa20``: The Salsa20 stream cipher + + - ``xmm``: Optimized implementation for x86/amd64 CPUs with SSE2 support + - ``nacl``: Use implementation from NaCl or libsodium + + * ``salsa2012``: The Salsa20/12 stream cipher + + - ``xmm``: Optimized implementation for x86/amd64 CPUs with SSE2 support + - ``nacl``: Use implementation from NaCl or libsodium + + +| ``drop capabilities yes|no|early;`` + + By default, fastd switches to the configured user and/or drops its + POSIX capabilities after the on up command has been run. + When drop capabilities is set to early, the on up command + is run after the privileges have been dropped, when set to no, the POSIX capabilities + aren't dropped at all (but the user is switched after the on up command + has been run nevertheless). + +| ``forward yes|no;`` + + Enables or disabled forwarding packets between peers. Care must be taken not to create forwarding loops. + +| ``group "<group>";`` + + Sets the group to run fastd as. + +| ``hide ip addresses yes|no;`` + + Hides IP addresses in log output. + +| ``hide mac addresses yes|no;`` + + Hides MAC addresses in log output. + +| ``include "<file>";`` + + Includes another configuration file. Relative paths are interpreted relatively to the + including file. + +| ``include peer "<file>" [ as "<name>" ];`` + + Includes a peer configuration (and optionally gives the peer a name). + +| ``include peers from "<dir>";`` + + Includes each file in a directory as a peer configuration. These peers are reloaded when + fastd receives a SIGHUP signal. + +| ``interface "<name>";`` + + Sets the name of the TUN/TAP interface to use; it will be set by the OS when no name is configured explicitly. + +| ``log level fatal|error|warn|info|verbose|debug|debug2;`` + + Sets the default log level, meaning syslog if there is currently a level set for syslog, and stderr + otherwise. + +| ``log to stderr level fatal|error|warn|info|verbose|debug|debug2;`` + + Sets the stderr log level. By default no log messages are printed on stderr, unless no other + log destination is configured, which causes fastd to log to stderr with level info. + +| ``log to syslog [ as "<ident>" ] [ level fatal|error|warn|info|verbose|debug|debug2 ];`` + + Sets the syslog log level. By default syslog isn't used. + +| ``mac "<MAC>" use "<implementation>";`` + + Chooses a specific impelemenation for a message authentication code. Normally, the default setting is already the best + choice. Note that specific implementations may be unavailable on some platforms or disabled during compilation. + The available MACs and implementations are: + + * ``ghash``: The MAC used by the GCM and GMAC methods + + - ``pclmulqdq``: An optimized implementation for modern x86/amd64 CPUs supporting the PCLMULQDQ instruction + - ``builtin``: A generic implementation + + * ``uhash``: The MAC used by the UMAC methods + + - ``builtin``: A generic implementation + +| ``method "<method>";`` + + Sets the encryption/authentication method. See the page :doc:`methods` for more information about the supported methods. + When multiple method statements are given, the first one has the highest preference. + +| ``mode tap|tun;`` + + Sets the mode of the interface; the default is TAP mode. + +| ``mtu <MTU>;`` + + Sets the MTU; must be at least 576. You should read the page :doc:`mtu` as the default 1500 is suboptimal in most setups. + +| ``on pre-up [ sync | async ] "<command>";`` +| ``on up [ sync | async ] "<command>";`` +| ``on down [ sync | async ] "<command>";`` +| ``on post-down [ sync | async ] "<command>";`` +| ``on connect [ sync | async ] "<command>";`` +| ``on establish [ sync | async ] "<command>";`` +| ``on disestablish [ sync | async ] "<command>";`` + + Configures a shell command that is run after the interface is created, before the interface is destroyed, + when a handshake is sent to make a new connection, + when a new peer connection has been established, or after a peer connection has been lost. fastd will + block until the command has finished, to long-running processes should be started in the background. + + pre-up, up, down and post-down commands are executed synchronously by default, meaning fastd will block + until the commands have finished, while the other commands are executed asynchronously by default. This + can be changed using the keywords sync and async. + + The following environment variables are set by fastd for all commands: + + * ``FASTD_PID``: fastd's PID + * ``INTERFACE``: the interface name + * ``INTERFACE_MTU``: the configured MTU + * ``LOCAL_KEY``: the local public key + + For on connect, on establish and on disestablish the following variables are set in addition: + + * ``LOCAL_ADDRESS``: the local IP address + * ``LOCAL_PORT``: the local UDP port + * ``PEER_ADDRESS``: the peer's IP address + * ``PEER_PORT``: the peer's UDP port + * ``PEER_NAME``: the peer's name in the local configuration + * ``PEER_KEY``: the peer's public key + +| ``on verify [ sync | async ] "<command>";`` + + Configures a shell command that is run on connection attempts by unknown peers. The same environment + variables as in the on establish command are supplied. When the commands returns 0, the + connection is accepted, otherwise the handshake is ignored. By default, fastd ignores connections + from unknown peers. + + Verify commands are executed asynchronously by default. This + can be changed using the keywords sync and async. + +| ``packet mark <mark>;`` + + Defines a packet mark to set on fastd's packets, which can be used in an ip rule. + + Marks can be specified in decimal, hexadecimal (with a leading 0x), and octal (with a leading 0). + +| ``peer "<name>" {`` *peer configuration* ``}`` + + An inline peer configuration. + +| ``peer group "<name>" {`` *configuration* ``}`` + + Configures a peer group. + +| ``peer limit <limit>;`` + + Sets the maximum number of connections for the current peer group. + +.. _option-pmtu: + +| ``pmtu yes|no|auto;`` + + Enables or disables Path MTU detection for IPv4. If enabled, all packets are sent with DF set, and all + fragmentation happens on the sending host itself. If disabled, routers may fragment the packets themselves, + possibly leading to multiple fragmentation. In general, disabling this should not be necessary, but in some + networks ICMP MTU Too Big packets are lost, so PMTU detection doesn't work correctly. + + If possible, fastd's mtu setting should be adjusted so the packets aren't fragmented at all instead of + relying on this option. + + The default is auto, which uses the system default as specified in /proc/sys/net/ipv4/ip_no_pmtu_disc. + + The pmtu option is available on Linux platforms only. + +| ``protocol "<protocol>";`` + + Sets the handshake protocol; at the moment only ec25519-fhmqvc is supported. + +| ``secret "<secret>";`` + + Sets the secret key. + +| ``secure handshakes yes|no;`` + + fastd v11+ implements a revised handshake scheme which prevents downgrade attacks (i.e. an attacker forcing + two peers to use the least secure encryption method supported by both sides, or even half-establishing a + session with an encryption method supported by one side only). To maintain backwards compatiblity, the old + handshake is still supported when secure handshakes is set to no. + + Setting this option to yes (the default) on one side is enough to ensure that a session established by two peers has not + been downgraded. + +| ``user "<user>";`` + +Sets the user to run fastd as. + +Peer configuration +------------------ + +Example config: + +:: + + key "f05c6f62337d291e34f50897d89b02ae43a6a2476e2969d1c8e8104fd11c1873"; + remote 192.0.2.1:10000; + remote [2001:db8::1]:10000; + remote ipv4 "fastd.example.com" port 10000; + +| ``include "<file>";`` + + Includes another configuration file. + +| ``key "<key>";`` + + Sets the peer's public key. + +| ``remote <IPv4 address>:<port>;`` +| ``remote <IPv6 address>:<port>;`` +| ``remote [ ipv4|ipv6 ] "<hostname>":<port>;`` +| ``remote <IPv4 address> port <port>;`` +| ``remote <IPv6 address> port <port>;`` +| ``remote [ ipv4|ipv6 ] "<hostname>" port <port>;`` + + Sets the IP address or host name to connect to. If a peer doesn't have a remote address configured, + incoming connections are accepted, but no own connection attempts will be made. + + The ipv4 or ipv6 options can be used to force fastd to resolve the host name for the + specified protocol version only. + + Starting with fastd v9, multiple remotes may be given for a single peer. If this is the case, they + will be tried one after another. Starting with fastd v11, all addresses a given hostname resolves + to are taken into account, not only the first one. This can be use to specify alternative hostname, + addresses and/or ports for the same host; all remotes must still refer to the same peer as the public + key must be unique. + +| ``float yes|no;`` + + The float option can be used to accept connections from the peer with the specified key from + other addresses that the configured ones. diff --git a/doc/source/manual/methods.rst b/doc/source/manual/methods.rst new file mode 100644 index 0000000..e4ea962 --- /dev/null +++ b/doc/source/manual/methods.rst @@ -0,0 +1,100 @@ +Encryption & authentication methods +=================================== +fastd supports various combinations of ciphers and authentication schemes using +different method providers. All ciphers, message authentication codes (MACs) and +method providers can be disabled during compilation to reduce the binary size. + +See `Benchmarks <https://projects.universe-factory.net/projects/fastd/wiki/Benchmarks>`_ for an +overview of the performance of the different methods. + +Recommended methods +~~~~~~~~~~~~~~~~~~~ +The method ``salsa2012+umac`` is recommended for authenticated encyption. ``null+salsa2012+umac`` is the +recommended method for authenticated-only operation. + +Salsa20/12 is a stream cipher with very high speed and a very comfortable security margin. +It has been chosed for the software profile in the `eSTREAM <http://en.wikipedia.org/wiki/ESTREAM>`_ project in 2008. + +`UMAC <http://en.wikipedia.org/wiki/UMAC>`_ is an extremely fast message authentication code which is provably +secure and optimized for software implementations. + +OpenWrt +------- +Too keep the binary as small as possible, only the following methods are enabled on OpenWrt +by default: + +* ``salsa2012+gmac`` +* ``salsa2012+umac`` +* ``null+salsa2012+gmac`` +* ``null+salsa2012+umac`` +* ``null`` + +Of these, the GMAC-based methods may be dropped in the future to further reduce the binary size, as UMAC is +the superior authentication scheme (it is faster than GMAC, provably secure and its software implementation +isn't suspect to timing side channels). + +List of methods +~~~~~~~~~~~~~~~ + +Encrypted methods +----------------- +======================= ================ ========== ========= ====== +Method Method provider Cipher MAC Notes +======================= ================ ========== ========= ====== +``aes128-gcm`` generic-gmac aes128-ctr ghash [2]_ +``salsa20+gmac`` generic-gmac salsa20 ghash +``salsa2012+gmac`` generic-gmac salsa2012 ghash +``aes128-ctr+umac`` generic-umac aes128-ctr uhash [2]_ +``salsa20+umac`` generic-umac salsa20 uhash +``salsa2012+umac`` generic-umac salsa2012 uhash +``aes128-ctr+poly1305`` generic-poly1305 aes128-ctr none [1]_ [2]_, [3]_ +``salsa20+poly1305`` generic-poly1305 salsa20 none [1]_ [3]_ +``salsa2012+poly1305`` generic-poly1305 salsa2012 none [1]_ [3]_ +======================= ================ ========== ========= ====== + +This list is not exhaustive. It is possible to combine different ciphers for +data and authentication tag encryption using the *composed-gmac* and *composed-umac* +method providers; these methods aren't listed here as this is not very useful. + +Authenticated-only methods +-------------------------- +======================== ================ ========== ===== ====== +Method Method provider Cipher MAC Notes +======================== ================ ========== ===== ====== +``null+aes128-gmac`` composed-gmac aes128-ctr ghash [2]_, [4]_ +``null+salsa20+gmac`` composed-gmac salsa20 ghash [4]_ +``null+salsa2012+gmac`` composed-gmac salsa2012 ghash [4]_ +``null+aes128-ctr+umac`` composed-umac aes128-ctr uhash [2]_, [4]_ +``null+salsa20+umac`` composed-umac salsa20 uhash [4]_ +``null+salsa2012+umac`` composed-umac salsa2012 uhash [4]_ +======================== ================ ========== ===== ====== + +Methods without security +------------------------ +======== =============== ====== ==== ===== +Method Method provider Cipher MAC Notes +======== =============== ====== ==== ===== +``null`` null none none [5]_ +======== =============== ====== ==== ===== + + +Deprecated methods +------------------ + +======================== ================= ========== ===== ====== +Method Method provider Cipher MAC Notes +======================== ================= ========== ===== ====== +``xsalsa20-poly1305`` xsalsa20-poly1305 none none [6]_ +======================== ================= ========== ===== ====== + + Since fastd v11 ``salsa20+poly1305`` should be used instead (or even better a more performant + method like salsa2012+gmac); ``xsalsa20-poly1305`` will be removed eventually. + + +.. [1] The MAC is integrated in the method provider. +.. [2] AES is very slow without OpenSSL support. OpenSSL's AES implementation may be suspect to cache timing side channels when no hardware support like AES-NI is available. +.. [3] Poly1305 is very slow on embedded systems. +.. [4] The cipher is used to encrypt the authentication tag only, the actual data is transmitted unencrypted. +.. [5] Only authentication of peers' IP addresses, but no encryption or authentication of any data is provided. +.. [6] Both the cipher and the MAC are integrated in the method provider. + diff --git a/doc/source/manual/mtu.rst b/doc/source/manual/mtu.rst new file mode 100644 index 0000000..68731e0 --- /dev/null +++ b/doc/source/manual/mtu.rst @@ -0,0 +1,30 @@ +MTU configuration +================= +The default MTU of fastd is 1500. This allows briding the fastd interface in TAP +mode with other interface with the same MTU, but will usually cause fastd's UDP +packets to be fragmented (see also the option :ref:`pmtu <option-pmtu>`). Fragmentation can lower the +performance or even cause connectivty problems when broken routers filter ICMP packets, +so if possible the MTU should be chosed small enough so that IP fragmentation can be avoided. +Unlike OpenVPN, fastd doesn't support fragmentation itself, but relies on the IP stack to fragment packets when necessary. + +Guidelines +---------- + +* The basic overhead of a fastd packet in TUN mode over IPv4 is 39 Bytes when only null crypto is used and 52 Bytes for all other crypto methods +* TAP mode needs 14 bytes more than TUN mode +* Tunneling over IPv6 needs 20 bytes more than IPv4 + +Examples +-------- + +Your base MTU is 1500 and you want to use TUN mode over IPv4 with any crypto method: + Choose 1500 - 52 = 1448 bytes. + +Your base MTU is 1492 (like most German DSL lines) and you want to use TAP mode over IPv4 with any crypto method: + Choose 1492 - 52 - 14 = 1426 bytes. + +Conservative choice when you want to transfer IPv6 inside the tunnel: + Choose 1280 Bytes (not relevant when you use batman-adv inside the tunnel as batman-adv will take care of the inner fragmentation). + +Conservative choice when you don't know anything (but assume the base MTU is at least 1280 so IPv6 can be supported) and want to support tunnels over IPv4 and IPv6 in TAP mode with any crypto method: + Choose 1280 - 52 - 14 - 20 = 1194 bytes. |