doc/man/gnunet.conf.5.in

   1 .\" -*- mode: nroff -*-
   2 .\" This file is part of Ascension.
   3 .\" Copyright (C) 2012-2015,2018,2019 GNUnet e.V.
   4 .\"
   5 .\" Permission is granted to copy, distribute and/or modify this document
   6 .\" under the terms of the GNU Free Documentation License, Version 1.3 or
   7 .\" any later version published by the Free Software Foundation; with no
   8 .\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
   9 .\" copy of the license is included in the file
  10 .\" ``FDL-1.3''.
  11 .\"
  12 .\" A copy of the license is also available from the Free Software
  13 .\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.
  14 .\"
  15 .\" Alternately, this document is also available under the General
  16 .\" Public License, version 3 or later, as published by the Free Software
  17 .\" Foundation.  A copy of the license is included in the file
  18 .\" ``GPL3''.
  19 .\"
  20 .\" A copy of the license is also available from the Free Software
  21 .\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}.
  22 .\"
  23 .\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later
  24 .\"
  25 .TH GNUNET.CONF "5" "October 26, 2018" "GNUnet"
  26 .SH NAME
  27 gnunet.conf \- GNUnet configuration file
  28 .SH SYNOPSIS
  29 ~/.config/gnunet.conf
  30 .SH DESCRIPTION
  31 A GNUnet setup typically consists of a set of service processes run by a user
  32 "gnunet" and a set of user-interface processes run by a standard account.
  33 The default location for the configuration file for the services is
  34 "~gnunet/.config/gnunet.conf"; however, as normal users also may need
  35 read-access to this configuration, you might want to instead put the service
  36 process configuration in "@SYSCONFDIR@/gnunet.conf".
  37 gnunet\-setup (part of the GNUnet GTK package) can be used to edit this
  38 configuration.  The parts of GNUnet that are run as a normal user may have
  39 config options too and they read from "$HOME/.config/gnunet.conf".
  40 The latter config file can skip any options for the services.
  41 .PP
  42 The basic structure of the configuration file is the following.  The file is
  43 split into sections.  Every section begins with "[SECTIONNAME]" and contains
  44 a number of options of the form "OPTION=VALUE".
  45 Empty lines and lines beginning with a "#" are treated as comments.
  46 Almost all options are optional and the tools resort to reasonable defaults
  47 if they are not present.
  48 .PP
  49 Default values for all of the options can be found in the files in the
  50 "$GNUNET_PREFIX/share/gnunet/config.d/" directory. A typical setup will
  51 work out of the box with those. See the examples section below for
  52 some common setups on top of that.
  53 .SS GENERAL OPTIONS
  54 Many options will be common between sections. They can be repeated under
  55 each section with different values.  The "[PATHS]" section is special.
  56 Here, it is possible to specify values for variables like "GNUNET_HOME".
  57 Then, in all filenames that begin with "$GNUNET_HOME" the "$GNUNET_HOME"
  58 will be replaced with the respective value at runtime.  The main use of
  59 this is to redefine "$GNUNET_HOME", which by default points to "$HOME/.config/".
  60 By setting this variable, you can change the location where GNUnet stores
  61 its internal data.
  62 gnunet.conf accepts the variable "GNUNET_TMP" which we suggest to use in
  63 place of the absolute definition of "/tmp".
  64 So instead of "/tmp/foo" you would write "$GNUNET_TMP/foo".
  65  The usage of "$GNUNET_TMP/foo", will result in "$TMPDIR/gnunet/foo", or
  66  "$TMP/gnunet/foo" and finally, if "TMPDIR" is undefined, "/tmp/gnunet/foo".
  67 .PP
  68 The following options are generic and shared by all services:
  69 .IP HOSTNAME
  70     The hostname specifies the machine on which the service is running.
  71     This is usually "localhost".
  72 .IP BINARY
  73     The filename that implements the service. For example "gnunet-service-ats".
  74 .IP IMMEDIATE_START
  75     Start the service always when the peer starts.  Set to YES for services
  76     that should always be launched, even if no other service explicitly needs
  77     them.
  78 .IP START_ON_DEMAND
  79     Set to YES to automatically start the service when it is requested by
  80     another service. YES for most GNUnet services.
  81 .IP NOARMBIND
  82     Set to YES to never have ARM bind to the respective socket. This option is
  83     mostly for debugging in situations where ARM cannot pass the pre-bound
  84     socket to the child due to interference from PREFIX-commands.
  85     This option is only effective in combination with IMMEDIATE_START being YES.
  86     NO by default.
  87 .IP PREFIX
  88     PREFIX the given command (with its arguments) to the actual BINARY to be
  89     executed. Useful to run certain services under special supervisors (like
  90     strace or valgrind).  Typically used in combination with IMMEDIATE_START
  91     and NOARMBIND. Empty by default.
  92 .IP ACCEPT_FROM
  93     A semi-column separated list of IPv4 addresses that are allowed to use
  94     the service; usually 127.0.0.1.
  95 .IP ACCEPT_FROM6
  96     A semi-column separated list of IPv6 addresses that are allowed to use the
  97     service; usually ::1.
  98 .IP UNIXPATH
  99     Path to use for the UNIX domain socket for inter process communication with
 100     the service on POSIX systems.
 101 .IP UNIX_MATCH_UID
 102     If UNIX domain sockets are used, set this to YES if only users with the same
 103     UID are allowed to access the service.
 104 .IP UNIX_MATCH_GID
 105     If UNIX domain sockets are used, set this to YES if only users with the same
 106     GID are allowed to access the service.
 107 .IP RUN_PER_USER
 108     Set to YES if this service should be run per-user, NO if this is a system
 109     service.  End-users should never have to change the defaults GNUnet provides
 110     for this option.
 111 .SS ATS OPTIONS
 112 .IP UNSPECIFIED_QUOTA_IN
 113     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 114 .IP UNSPECIFIED_QUOTA_OUT
 115     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 116 .IP LOOPBACK_QUOTA_IN
 117     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 118 .IP LOOPBACK_QUOTA_OUT
 119     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 120 .IP LAN_QUOTA_IN
 121     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 122 .IP LAN_QUOTA_OUT
 123     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 124 .IP WAN_QUOTA_IN
 125     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 126 .IP WAN_QUOTA_OUT
 127     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 128 .IP WLAN_QUOTA_IN
 129     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 130 .IP WLAN_QUOTA_OUT
 131     quotes in KiB or MiB per seconds.  Or use the word "unlimited"
 132 .SH EXAMPLES
 133 This example is a simple way to get started, using a server that has a known
 134 list of peers to get you started. Most users will be behind a firewall on
 135 IPv4, as such NAT is enabled.  Please remember to change your IP address
 136 to the actual external address for your usage.
 137 .PP
 138     [hostlist]
 139     OPTIONS = \-b \-e
 140
 141     [nat]
 142     BEHIND_NAT = YES
 143     ENABLE_UPNP = YES
 144     DISABLEV6 = YES
 145     EXTERNAL_ADDRESS = 157.166.249.10
 146
 147     [arm]
 148     START_SYSTEM_SERVICES = YES
 149     START_USER_SERVICES = NO
 150 .SH FILES
 151 .TP
 152 ~/.config/gnunet.conf
 153 GNUnet configuration file
 154 .SH SEE ALSO
 155 \fBgnunet\-setup\fP(1), \fBgnunet\-arm\fP(1)
 156 .PP
 157 The full documentation for
 158 .B gnunet
 159 is maintained as a Texinfo manual.
 160 If the
 161 .B info
 162 and
 163 .B gnunet
 164 programs are properly installed at your site, the command
 165 .IP
 166 .B info gnunet
 167 .PP
 168 should give you access to the complete handbook,
 169 .IP
 170 .B info gnunet-c-tutorial
 171 .PP
 172 will give you access to a tutorial for developers.
 173 .PP
 174 Depending on your installation, this information is also
 175 available in
 176 \fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7).
 177 .SH HISTORY
 178 .PP
 179 This man page first appeared in October 2012 in GNUnet.
 180 .SH BUGS
 181 Report bugs by using Mantis <https://bugs.gnunet.org/> or by sending
 182 electronic mail to <bug-gnunet@gnu.org>