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