From 80753854f77f7d834e8d025ffa6dbb4680f6bf36 Mon Sep 17 00:00:00 2001 From: ng0 Date: Sat, 20 Apr 2019 12:12:25 +0000 Subject: gnunet.conf.5 --- doc/man/gnunet.conf.5.in | 278 ++++++++++++++++++++++++----------------------- 1 file changed, 142 insertions(+), 136 deletions(-) (limited to 'doc/man/gnunet.conf.5.in') 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 @@ .\" .\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later .\" -.TH GNUNET.CONF "5" "October 26, 2018" "GNUnet" -.SH NAME -gnunet.conf \- GNUnet configuration file -.SH SYNOPSIS -~/.config/gnunet.conf -.SH DESCRIPTION -A 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. +.Dd October 26, 2018 +.Dt GNUNET.CONF 5 +.Os +.Sh NAME +.Nm gnunet.conf +.Nd +GNUnet configuration file +.Sh DESCRIPTION +A 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. The default location for the configuration file for the services is -"~gnunet/.config/gnunet.conf"; however, as normal users also may need -read-access to this configuration, you might want to instead put the service -process configuration in "@SYSCONFDIR@/gnunet.conf". -gnunet\-setup (part of the GNUnet GTK package) can be used to edit this -configuration. The parts of GNUnet that are run as a normal user may have -config options too and they read from "$HOME/.config/gnunet.conf". +.Pa ~gnunet/.config/gnunet.conf Ns ; +however, as normal users also may need read-access to this configuration, you might want to instead put the service process configuration in +.Pa @SYSCONFDIR@/gnunet.conf Ns . +gnunet-setup (part of gnunet-gtk) can be used to edit this configuration. +The parts of GNUnet that are run as a normal user may have config options too and they read from +.Pa $HOME/.config/gnunet.conf Ns . The latter config file can skip any options for the services. -.PP -The basic structure of the configuration file is the following. The file is -split into sections. Every section begins with "[SECTIONNAME]" and contains -a number of options of the form "OPTION=VALUE". +.Pp +The basic structure of the configuration file is the following. +The file is split into sections. +Every section begins with "[SECTIONNAME]" and contains a number of options of the form "OPTION=VALUE". Empty lines and lines beginning with a "#" are treated as comments. -Almost all options are optional and the tools resort to reasonable defaults -if they are not present. -.PP +Almost all options are optional and the tools resort to reasonable defaults if they are not present. +.Pp Default values for all of the options can be found in the files in the -"$GNUNET_PREFIX/share/gnunet/config.d/" directory. A typical setup will -work out of the box with those. See the examples section below for -some common setups on top of that. -.SS GENERAL OPTIONS -Many options will be common between sections. They can be repeated under -each section with different values. The "[PATHS]" section is special. +.Pa $GNUNET_PREFIX/share/gnunet/config.d/ +directory. +A typical setup will work out of the box with those. +See the examples section below for some common setups on top of that. +.Ss GENERAL OPTIONS +Many options will be common between sections. +They can be repeated under each section with different values. +The "[PATHS]" section is special. Here, it is possible to specify values for variables like "GNUNET_HOME". -Then, in all filenames that begin with "$GNUNET_HOME" the "$GNUNET_HOME" -will be replaced with the respective value at runtime. The main use of -this is to redefine "$GNUNET_HOME", which by default points to "$HOME/.config/". -By setting this variable, you can change the location where GNUnet stores -its internal data. -gnunet.conf accepts the variable "GNUNET_TMP" which we suggest to use in -place of the absolute definition of "/tmp". -So instead of "/tmp/foo" you would write "$GNUNET_TMP/foo". - The usage of "$GNUNET_TMP/foo", will result in "$TMPDIR/gnunet/foo", or - "$TMP/gnunet/foo" and finally, if "TMPDIR" is undefined, "/tmp/gnunet/foo". -.PP +Then, in all filenames that begin with "$GNUNET_HOME" the "$GNUNET_HOME" will be replaced with the respective value at runtime. +The main use of this is to redefine "$GNUNET_HOME", which by default points to +.Pa $HOME/.config/ Ns . +By setting this variable, you can change the location where GNUnet stores its internal data. +.Pa gnunet.conf +accepts the variable "GNUNET_TMP" which we suggest to use in place of the absolute definition of +.Pa /tmp Ns . +So instead of +.Pa /tmp/foo +you would write "$GNUNET_TMP/foo". +The usage of "$GNUNET_TMP/foo", will result in "$TMPDIR/gnunet/foo", or "$TMP/gnunet/foo" and finally, if "TMPDIR" is undefined, "/tmp/gnunet/foo". The following options are generic and shared by all services: -.IP HOSTNAME - The hostname specifies the machine on which the service is running. - This is usually "localhost". -.IP BINARY - The filename that implements the service. For example "gnunet-service-ats". -.IP IMMEDIATE_START - Start the service always when the peer starts. Set to YES for services - that should always be launched, even if no other service explicitly needs - them. -.IP START_ON_DEMAND - Set to YES to automatically start the service when it is requested by - another service. YES for most GNUnet services. -.IP NOARMBIND - Set to YES to never have ARM bind to the respective socket. This option is - mostly for debugging in situations where ARM cannot pass the pre-bound - socket to the child due to interference from PREFIX-commands. - This option is only effective in combination with IMMEDIATE_START being YES. - NO by default. -.IP PREFIX - PREFIX the given command (with its arguments) to the actual BINARY to be - executed. Useful to run certain services under special supervisors (like - strace or valgrind). Typically used in combination with IMMEDIATE_START - and NOARMBIND. Empty by default. -.IP ACCEPT_FROM - A semi-column separated list of IPv4 addresses that are allowed to use - the service; usually 127.0.0.1. -.IP ACCEPT_FROM6 - A semi-column separated list of IPv6 addresses that are allowed to use the - service; usually ::1. -.IP UNIXPATH - Path to use for the UNIX domain socket for inter process communication with - the service on POSIX systems. -.IP UNIX_MATCH_UID - If UNIX domain sockets are used, set this to YES if only users with the same - UID are allowed to access the service. -.IP UNIX_MATCH_GID - If UNIX domain sockets are used, set this to YES if only users with the same - GID are allowed to access the service. -.IP RUN_PER_USER - Set to YES if this service should be run per-user, NO if this is a system - service. End-users should never have to change the defaults GNUnet provides - for this option. -.SS ATS OPTIONS -.IP UNSPECIFIED_QUOTA_IN - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP UNSPECIFIED_QUOTA_OUT - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP LOOPBACK_QUOTA_IN - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP LOOPBACK_QUOTA_OUT - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP LAN_QUOTA_IN - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP LAN_QUOTA_OUT - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP WAN_QUOTA_IN - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP WAN_QUOTA_OUT - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP WLAN_QUOTA_IN - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.IP WLAN_QUOTA_OUT - quotes in KiB or MiB per seconds. Or use the word "unlimited" -.SH EXAMPLES -This example is a simple way to get started, using a server that has a known -list of peers to get you started. Most users will be behind a firewall on -IPv4, as such NAT is enabled. Please remember to change your IP address -to the actual external address for your usage. -.PP +.Bl -tag -width Ds +.It HOSTNAME +The hostname specifies the machine on which the service is running. +This is usually "localhost". +.It BINARY +The filename that implements the service. +For example "gnunet-service-ats". +.It IMMEDIATE_START +Start the service always when the peer starts. +Set to YES for services that should always be launched, even if no other service explicitly needs them. +.It START_ON_DEMAND +Set to YES to automatically start the service when it is requested by another service. +YES for most GNUnet services. +.It NOARMBIND +Set to YES to never have ARM bind to the respective socket. +This option is mostly for debugging in situations where ARM cannot pass the pre-bound socket to the child due to interference from PREFIX-commands. +This option is only effective in combination with IMMEDIATE_START being YES. +NO by default. +.It PREFIX +PREFIX the given command (with its arguments) to the actual BINARY to be executed. +Useful to run certain services under special supervisors (like strace or valgrind). +Typically used in combination with IMMEDIATE_START and NOARMBIND. +Empty by default. +.It ACCEPT_FROM +A semi-column separated list of IPv4 addresses that are allowed to use the service; usually 127.0.0.1. +.It ACCEPT_FROM6 +A semi-column separated list of IPv6 addresses that are allowed to use the service; usually ::1. +.It UNIXPATH +Path to use for the UNIX domain socket for inter process communication with the service on POSIX systems. +.It UNIX_MATCH_UID +If UNIX domain sockets are used, set this to YES if only users with the same UID are allowed to access the service. +.It UNIX_MATCH_GID +If UNIX domain sockets are used, set this to YES if only users with the same GID are allowed to access the service. +.It RUN_PER_USER +Set to YES if this service should be run per-user, NO if this is a system service. +End-users should never have to change the defaults GNUnet provides for this option. +.El +.Ss ATS OPTIONS +.Bl -tag -width Ds +.It UNSPECIFIED_QUOTA_IN +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It UNSPECIFIED_QUOTA_OUT +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It LOOPBACK_QUOTA_IN +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It LOOPBACK_QUOTA_OUT +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It LAN_QUOTA_IN +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It LAN_QUOTA_OUT +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It WAN_QUOTA_IN +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It WAN_QUOTA_OUT +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It WLAN_QUOTA_IN +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.It WLAN_QUOTA_OUT +quotes in KiB or MiB per seconds. +Or use the word "unlimited" +.El +.Sh EXAMPLES +This example is a simple way to get started, using a server that has a known list of peers to get you started. +Most users will be behind a firewall on IPv4, as such NAT is enabled. +Please remember to change your IP address to the actual external address for your usage. +.Bd -literal -offset indent -compact [hostlist] OPTIONS = \-b \-e @@ -147,36 +155,34 @@ to the actual external address for your usage. [arm] START_SYSTEM_SERVICES = YES START_USER_SERVICES = NO -.SH FILES -.TP -~/.config/gnunet.conf +.Ed +.Sh FILES +.Pa ~/.config/gnunet.conf GNUnet configuration file -.SH SEE ALSO -\fBgnunet\-setup\fP(1), \fBgnunet\-arm\fP(1) -.PP -The full documentation for -.B gnunet -is maintained as a Texinfo manual. +.Sh SEE ALSO +.Xr gnunet-arm 1 , +.Xr gnunet-setup 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. If the -.B info -and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). -.SH HISTORY -.PP -This man page first appeared in October 2012 in GNUnet. -.SH BUGS -Report bugs by using Mantis or by sending -electronic mail to +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . -- cgit v1.2.3