diff options
author | ng0 <ng0@infotropique.org> | 2017-10-20 22:05:30 +0000 |
---|---|---|
committer | ng0 <ng0@infotropique.org> | 2017-10-20 22:05:30 +0000 |
commit | f454f1fc042c42ee1dc87c7837b655a45ef327b5 (patch) | |
tree | 77b048609ff4b08530057449a0f704b899cec70d | |
parent | 014558c7599a562b227c7fb4d19d3db961d9f1f1 (diff) | |
download | gnunet-f454f1fc042c42ee1dc87c7837b655a45ef327b5.tar.gz gnunet-f454f1fc042c42ee1dc87c7837b655a45ef327b5.zip |
edits in installation.texi
-rw-r--r-- | doc/chapters/installation.texi | 1926 |
1 files changed, 1028 insertions, 898 deletions
diff --git a/doc/chapters/installation.texi b/doc/chapters/installation.texi index 60861402a..c7f15f335 100644 --- a/doc/chapters/installation.texi +++ b/doc/chapters/installation.texi | |||
@@ -1707,47 +1707,42 @@ unpack it to the MinGW directory (c:\mingw\mingw) | |||
1707 | @ | 1707 | @ |
1708 | Get the prebuilt binary from here and unpack it to your MinGW directory. | 1708 | Get the prebuilt binary from here and unpack it to your MinGW directory. |
1709 | 1709 | ||
1710 | @item | 1710 | @item @strong{MySQL}@ |
1711 | @strong{MySQL}@ | 1711 | As an alternative to SQLite, GNUnet also supports MySQL. |
1712 | @ | 1712 | |
1713 | As an alternative to SQLite, GNUnet also supports MySQL. | ||
1714 | @itemize @bullet | 1713 | @itemize @bullet |
1715 | 1714 | ||
1715 | @item Get the binary installer from the | ||
1716 | @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project} | ||
1717 | (version 4.1), install it and follow the instructions in README.mysql. | ||
1716 | 1718 | ||
1717 | @item | 1719 | @item Create a temporary build directory (c:\mysql) |
1718 | Get the binary installer from the @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project} (version 4.1),@ | ||
1719 | install it and follow the instructions in README.mysql. | ||
1720 | 1720 | ||
1721 | @item | 1721 | @item Copy the directories include\ and lib\ from the MySQL directory to |
1722 | Create a temporary build directory (c:\mysql) | 1722 | the new directory |
1723 | 1723 | ||
1724 | @item | 1724 | @item Get the patches from |
1725 | Copy the directories include\ and lib\ from the MySQL directory to the new directory | 1725 | @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and |
1726 | @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the | ||
1727 | latter is only required for MySQL | ||
1726 | 1728 | ||
1727 | @item | ||
1728 | Get the patches from @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the latter is only required for MySQL | ||
1729 | @example | 1729 | @example |
1730 | patch -p 0 | 1730 | patch -p 0 |
1731 | @end example | 1731 | @end example |
1732 | 1732 | ||
1733 | @item Move lib\opt\libmysql.dll to lib\libmysql.dll | ||
1733 | 1734 | ||
1734 | @item | 1735 | @item Change to lib\ and create an import library:@ |
1735 | Move lib\opt\libmysql.dll to lib\libmysql.dll | ||
1736 | |||
1737 | @item | ||
1738 | Change to lib\ and create an import library:@ | ||
1739 | 1736 | ||
1740 | @example | 1737 | @example |
1741 | dlltool --input-def ../include/libmySQL.def --dllname libmysql.dll | 1738 | dlltool --input-def ../include/libmySQL.def --dllname libmysql.dll |
1742 | --output-lib libmysqlclient.a -k | 1739 | --output-lib libmysqlclient.a -k |
1743 | @end example | 1740 | @end example |
1744 | 1741 | ||
1742 | @item Copy include\* to include\mysql\ | ||
1745 | 1743 | ||
1746 | @item | 1744 | @item Pass "--with-mysql=/c/mysql" to ./configure and copy libmysql.dll |
1747 | Copy include\* to include\mysql\ | 1745 | to your PATH or GNUnet's @file{bin} directory |
1748 | |||
1749 | @item | ||
1750 | Pass "--with-mysql=/c/mysql" to ./configure and copy libmysql.dll to your PATH or GNUnet's @file{bin} directory | ||
1751 | @end itemize | 1746 | @end itemize |
1752 | 1747 | ||
1753 | 1748 | ||
@@ -1756,85 +1751,110 @@ dlltool --input-def ../include/libmySQL.def --dllname libmysql.dll | |||
1756 | @ | 1751 | @ |
1757 | gnunet-gtk and libextractor depend on GTK.@ | 1752 | gnunet-gtk and libextractor depend on GTK.@ |
1758 | @ | 1753 | @ |
1759 | Get the the binary and developer packages of atk, glib, gtk, iconv, gettext-runtime, pango from @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the MinGW directory (c:\mingw\mingw)@ | 1754 | Get the the binary and developer packages of atk, glib, gtk, iconv, |
1755 | gettext-runtime, pango from | ||
1756 | @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the | ||
1757 | MinGW directory (c:\mingw\mingw)@ | ||
1760 | @ | 1758 | @ |
1761 | Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng and unpack them to the MinGW directory (c:\mingw\mingw)@ | 1759 | Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng |
1760 | and unpack them to the MinGW directory (c:\mingw\mingw)@ | ||
1762 | @ | 1761 | @ |
1763 | Here is an all-in-one package for @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}. Do not overwrite any existing files! | 1762 | Here is an all-in-one package for |
1763 | @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}. | ||
1764 | Do not overwrite any existing files! | ||
1764 | 1765 | ||
1765 | @item | 1766 | @item |
1766 | @strong{Glade}@ | 1767 | @strong{Glade}@ |
1767 | @ | 1768 | @ |
1768 | gnunet-gtk and and gnunet-setup were created using this interface builder@ | 1769 | gnunet-gtk and and gnunet-setup were created using this interface builder |
1769 | 1770 | ||
1770 | @itemize @bullet | 1771 | @itemize @bullet |
1771 | 1772 | ||
1772 | 1773 | ||
1773 | @item | 1774 | @item |
1774 | Get the Glade and libglade (-bin and -devel) packages (without GTK!) from @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to the MinGW directory (c:\mingw\mingw) | 1775 | Get the Glade and libglade (-bin and -devel) packages (without GTK!) from |
1776 | @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to | ||
1777 | the MinGW directory (c:\mingw\mingw) | ||
1775 | 1778 | ||
1776 | @item | 1779 | @item |
1777 | Get libxml from here and unpack it to the MinGW directory (c:\mingw\mingw). | 1780 | Get libxml from here and unpack it to the MinGW |
1781 | directory (c:\mingw\mingw). | ||
1778 | @end itemize | 1782 | @end itemize |
1779 | 1783 | ||
1780 | 1784 | ||
1781 | @item | 1785 | @item |
1782 | @strong{zLib}@ | 1786 | @strong{zLib}@ |
1783 | @ | 1787 | @ |
1784 | libextractor requires zLib to decompress some file formats. GNUnet uses it to (de)compress meta-data.@ | 1788 | libextractor requires zLib to decompress some file formats. GNUnet uses it |
1789 | to (de)compress meta-data.@ | ||
1785 | @ | 1790 | @ |
1786 | Get zLib from here (Signature) and unpack it to the MinGW directory (c:\mingw\mingw) | 1791 | Get zLib from here (Signature) and unpack it to the |
1792 | MinGW directory (c:\mingw\mingw) | ||
1787 | 1793 | ||
1788 | @item | 1794 | @item |
1789 | @strong{Bzip2}@ | 1795 | @strong{Bzip2}@ |
1790 | @ | 1796 | @ |
1791 | libextractor also requires Bzip2 to decompress some file formats.@ | 1797 | libextractor also requires Bzip2 to decompress some file formats.@ |
1792 | @ | 1798 | @ |
1793 | Get Bzip2 (binary and developer package) from @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and unpack it to the MinGW directory (c:\mingw\mingw) | 1799 | Get Bzip2 (binary and developer package) from |
1800 | @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and | ||
1801 | unpack it to the MinGW directory (c:\mingw\mingw) | ||
1794 | 1802 | ||
1795 | @item | 1803 | @item |
1796 | @strong{Libgcrypt}@ | 1804 | @strong{Libgcrypt}@ |
1797 | @ | 1805 | @ |
1798 | Libgcrypt provides the cryptographic functions used by GNUnet@ | 1806 | Libgcrypt provides the cryptographic functions used by GNUnet@ |
1799 | @ | 1807 | @ |
1800 | Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, compile and place it in the MinGW directory (c:\mingw\mingw). Currently you need at least version 1.4.2 to compile gnunet. | 1808 | Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, |
1809 | compile and place it in the MinGW directory (c:\mingw\mingw). Currently | ||
1810 | you need at least version 1.4.2 to compile GNUnet. | ||
1801 | 1811 | ||
1802 | @item | 1812 | @item |
1803 | @strong{PlibC}@ | 1813 | @strong{PlibC}@ |
1804 | @ | 1814 | @ |
1805 | PlibC emulates Unix functions under Windows.@ | 1815 | PlibC emulates Unix functions under Windows.@ |
1806 | @ | 1816 | @ |
1807 | Get PlibC from here and unpack it to the MinGW directory (c:\mingw\mingw) | 1817 | Get PlibC from here and unpack it to the MinGW |
1818 | directory (c:\mingw\mingw) | ||
1808 | 1819 | ||
1809 | @item | 1820 | @item |
1810 | @strong{OGG Vorbis}@ | 1821 | @strong{OGG Vorbis}@ |
1811 | @ | 1822 | @ |
1812 | OGG Vorbis is used to extract meta-data from .ogg files@ | 1823 | OGG Vorbis is used to extract meta-data from .ogg files@ |
1813 | @ | 1824 | @ |
1814 | Get the packages @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} and @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} from the @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} and unpack them to the MinGW directory (c:\mingw\mingw) | 1825 | Get the packages |
1826 | @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} | ||
1827 | and | ||
1828 | @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} | ||
1829 | from the | ||
1830 | @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} | ||
1831 | and unpack them to the MinGW directory (c:\mingw\mingw) | ||
1815 | 1832 | ||
1816 | @item | 1833 | @item |
1817 | @strong{Exiv2}@ | 1834 | @strong{Exiv2}@ |
1818 | @ | 1835 | @ |
1819 | (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@ | 1836 | (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@ |
1820 | @ | 1837 | @ |
1821 | Download @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} and unpack it to the MSYS directory (c:\mingw) | 1838 | Download |
1839 | @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} | ||
1840 | and unpack it to the MSYS directory (c:\mingw) | ||
1822 | @end itemize | 1841 | @end itemize |
1823 | 1842 | ||
1824 | @node Building libextractor and GNUnet | 1843 | @node Building libextractor and GNUnet |
1825 | @subsubsection Building libextractor and GNUnet | 1844 | @subsubsection Building libextractor and GNUnet |
1826 | 1845 | ||
1827 | Before you compile libextractor or GNUnet, be sure to set@ | 1846 | Before you compile libextractor or GNUnet, be sure to set PKG_CONFIG_PATH: |
1828 | PKG_CONFIG_PATH: | 1847 | |
1829 | @example | 1848 | @example |
1830 | export PKG_CONFIG_PATH=/mingw/lib/pkgconfig | 1849 | export PKG_CONFIG_PATH=/mingw/lib/pkgconfig |
1831 | @end example | 1850 | @end example |
1832 | 1851 | ||
1852 | @noindent | ||
1853 | See Installation for basic instructions on building libextractor | ||
1854 | and GNUnet. By default, all modules that are created in this way contain | ||
1855 | debug information and are quite large. To compile release versions (small | ||
1856 | and fast) set the variable CFLAGS: | ||
1833 | 1857 | ||
1834 | See Installation for basic instructions on building libextractor and GNUnet. | ||
1835 | |||
1836 | By default, all modules that are created in this way contain debug information and are quite large.@ | ||
1837 | To compile release versions (small and fast) set the variable CFLAGS: | ||
1838 | @example | 1858 | @example |
1839 | export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' | 1859 | export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' |
1840 | ./configure --prefix=$HOME --with-extractor=$HOME | 1860 | ./configure --prefix=$HOME --with-extractor=$HOME |
@@ -1843,8 +1863,9 @@ export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' | |||
1843 | @node Installer | 1863 | @node Installer |
1844 | @subsubsection Installer | 1864 | @subsubsection Installer |
1845 | 1865 | ||
1846 | The GNUnet installer is made with @uref{http://nsis.sourceforge.net/, NSIS}@ | 1866 | The GNUnet installer is made with |
1847 | The installer script is located in contrib\win in the GNUnet source tree. | 1867 | @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is |
1868 | located in @file{contrib\win} in the GNUnet source tree. | ||
1848 | 1869 | ||
1849 | @node Source | 1870 | @node Source |
1850 | @subsubsection Source | 1871 | @subsubsection Source |
@@ -1857,9 +1878,9 @@ The sources of all dependencies are available here. | |||
1857 | Quick instructions on how to use the most recent GNUnet on most GNU/Linux | 1878 | Quick instructions on how to use the most recent GNUnet on most GNU/Linux |
1858 | distributions | 1879 | distributions |
1859 | 1880 | ||
1860 | Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian and | 1881 | Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian |
1861 | CentOS 6, but it should work on almost any GNU/Linux distribution. More | 1882 | and CentOS 6, but it should work on almost any GNU/Linux distribution. |
1862 | in-detail information can be found in the handbook. | 1883 | More in-detail information can be found in the handbook. |
1863 | 1884 | ||
1864 | 1885 | ||
1865 | 1886 | ||
@@ -1879,11 +1900,12 @@ needed:@ | |||
1879 | @node Download & set up gnunet-update | 1900 | @node Download & set up gnunet-update |
1880 | @subsection Download & set up gnunet-update | 1901 | @subsection Download & set up gnunet-update |
1881 | 1902 | ||
1882 | The following command will download a working version of gnunet-update with the | 1903 | The following command will download a working version of gnunet-update |
1883 | subversion tool and import the public key which is needed for authentication:@ | 1904 | with the subversion tool and import the public key which is needed for |
1905 | authentication: | ||
1884 | 1906 | ||
1885 | @example | 1907 | @example |
1886 | svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update && | 1908 | svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update |
1887 | cd ~/gnunet-update | 1909 | cd ~/gnunet-update |
1888 | gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 | 1910 | gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 |
1889 | @end example | 1911 | @end example |
@@ -1891,35 +1913,37 @@ gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 | |||
1891 | @node Install GNUnet | 1913 | @node Install GNUnet |
1892 | @subsection Install GNUnet | 1914 | @subsection Install GNUnet |
1893 | 1915 | ||
1894 | Download and install GNUnet binaries which can be found here and set library | 1916 | Download and install GNUnet binaries which can be found here and set |
1895 | paths:@ | 1917 | library paths: |
1896 | @code{@ | 1918 | |
1897 | wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz@ | 1919 | @example |
1898 | ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~@ | 1920 | wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz |
1899 | echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment@ | 1921 | ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~ |
1900 | echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee /etc/ld.so.conf.d/gnunet.conf > /dev/null@ | 1922 | echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment |
1901 | sudo ldconfig@ | 1923 | echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \ |
1902 | }@ | 1924 | /etc/ld.so.conf.d/gnunet.conf > /dev/null |
1925 | sudo ldconfig | ||
1926 | @end example | ||
1903 | 1927 | ||
1904 | You may need to re-login once after executing these last commands | 1928 | You may need to re-login once after executing these last commands |
1905 | 1929 | ||
1906 | That's it, GNUnet is installed in your home directory now. GNUnet can be | 1930 | That's it, GNUnet is installed in your home directory now. GNUnet can be |
1907 | configured and afterwards started by executing@ | 1931 | configured and afterwards started by executing @code{gnunet-arm -s}. |
1908 | @code{gnunet-arm -s} | ||
1909 | 1932 | ||
1910 | @node The graphical configuration interface | 1933 | @node The graphical configuration interface |
1911 | @section The graphical configuration interface | 1934 | @section The graphical configuration interface |
1912 | 1935 | ||
1913 | If you also would like to use gnunet-gtk and gnunet-setup (highly recommended | 1936 | If you also would like to use gnunet-gtk and gnunet-setup (highly |
1914 | for beginners), do: | 1937 | recommended for beginners), do: |
1915 | 1938 | ||
1916 | @example | 1939 | @example |
1917 | wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz@ | 1940 | wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz |
1918 | sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~@ | 1941 | sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~ |
1919 | sudo ldconfig | 1942 | sudo ldconfig |
1920 | @end example | 1943 | @end example |
1921 | Now you can run @code{gnunet-setup} for easy configuration of your GNUnet peer. | ||
1922 | 1944 | ||
1945 | Now you can run @code{gnunet-setup} for easy configuration of your | ||
1946 | GNUnet peer. | ||
1923 | 1947 | ||
1924 | @menu | 1948 | @menu |
1925 | * Configuring your peer:: | 1949 | * Configuring your peer:: |
@@ -1961,115 +1985,124 @@ Now you can run @code{gnunet-setup} for easy configuration of your GNUnet peer. | |||
1961 | This chapter will describe the various configuration options in GNUnet. | 1985 | This chapter will describe the various configuration options in GNUnet. |
1962 | 1986 | ||
1963 | The easiest way to configure your peer is to use the gnunet-setup tool. | 1987 | The easiest way to configure your peer is to use the gnunet-setup tool. |
1964 | gnunet-setup is part of the gnunet-gtk download. You might have to install it | 1988 | gnunet-setup is part of the gnunet-gtk download. You might have to |
1965 | separately. | 1989 | install it separately. |
1966 | |||
1967 | Many of the specific sections from this chapter actually are linked from within | ||
1968 | gnunet-setup to help you while using the setup tool. | ||
1969 | |||
1970 | While you can also configure your peer by editing the configuration file by | ||
1971 | hand, this is not recommended for anyone except for developers. | ||
1972 | |||
1973 | 1990 | ||
1991 | Many of the specific sections from this chapter actually are linked from | ||
1992 | within gnunet-setup to help you while using the setup tool. | ||
1974 | 1993 | ||
1994 | While you can also configure your peer by editing the configuration | ||
1995 | file by hand, this is not recommended for anyone except for developers. | ||
1975 | 1996 | ||
1976 | 1997 | ||
1977 | @node Configuring the Friend-to-Friend (F2F) mode | 1998 | @node Configuring the Friend-to-Friend (F2F) mode |
1978 | @subsection Configuring the Friend-to-Friend (F2F) mode | 1999 | @subsection Configuring the Friend-to-Friend (F2F) mode |
1979 | 2000 | ||
1980 | GNUnet knows three basic modes of operation. In standard "peer-to-peer" mode, | 2001 | GNUnet knows three basic modes of operation. In standard "peer-to-peer" |
1981 | your peer will connect to any peer. In the pure "friend-to-friend" mode, your | 2002 | mode, your peer will connect to any peer. In the pure "friend-to-friend" |
1982 | peer will ONLY connect to peers from a list of friends specified in the | 2003 | mode, your peer will ONLY connect to peers from a list of friends |
1983 | configuration. Finally, in mixed mode, GNUnet will only connect to arbitrary | 2004 | specified in the configuration. |
1984 | peers if it has at least a specified number of connections to friends. | 2005 | Finally, in mixed mode, GNUnet will only connect to arbitrary peers if it |
2006 | has at least a specified number of connections to friends. | ||
1985 | 2007 | ||
1986 | When configuring any of the F2F modes, you first need to create a file with the | 2008 | When configuring any of the F2F modes, you first need to create a file |
1987 | peer identities of your friends. Ask your friends to run | 2009 | with the peer identities of your friends. Ask your friends to run |
1988 | 2010 | ||
2011 | @example | ||
1989 | $ gnunet-peerinfo -sq | 2012 | $ gnunet-peerinfo -sq |
2013 | @end example | ||
1990 | 2014 | ||
1991 | The output of this command needs to be added to your friends file, which is | 2015 | @noindent |
1992 | simply a plain text file with one line per friend with the output from the | 2016 | The output of this command needs to be added to your friends file, which |
1993 | above command. | 2017 | is simply a plain text file with one line per friend with the output from |
2018 | the above command. | ||
1994 | 2019 | ||
1995 | You then specify the location of your friends file in the "FRIENDS" option of | 2020 | You then specify the location of your friends file in the "FRIENDS" |
1996 | the "topology" section. | 2021 | option of the "topology" section. |
1997 | 2022 | ||
1998 | Once you have created the friends file, you can tell GNUnet to only connect to | 2023 | Once you have created the friends file, you can tell GNUnet to only |
1999 | your friends by setting the "FRIENDS-ONLY" option (again in the "topology" | 2024 | connect to your friends by setting the "FRIENDS-ONLY" option (again in |
2000 | section) to YES. | 2025 | the "topology" section) to YES. |
2001 | 2026 | ||
2002 | If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a | 2027 | If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a |
2003 | minimum number of friends to have (before connecting to arbitrary peers) under | 2028 | minimum number of friends to have (before connecting to arbitrary peers) |
2004 | the "MINIMUM-FRIENDS" option. | 2029 | under the "MINIMUM-FRIENDS" option. |
2005 | 2030 | ||
2006 | If you want to operate in normal P2P-only mode, simply set "MINIMUM-FRIENDS" to | 2031 | If you want to operate in normal P2P-only mode, simply set |
2007 | zero and "FRIENDS_ONLY" to NO. This is the default. | 2032 | "MINIMUM-FRIENDS" to zero and "FRIENDS_ONLY" to NO. This is the default. |
2008 | 2033 | ||
2009 | @node Configuring the hostlist to bootstrap | 2034 | @node Configuring the hostlist to bootstrap |
2010 | @subsection Configuring the hostlist to bootstrap | 2035 | @subsection Configuring the hostlist to bootstrap |
2011 | 2036 | ||
2012 | After installing the software you need to get connected to the GNUnet network. | 2037 | After installing the software you need to get connected to the GNUnet |
2013 | The configuration file included in your download is already configured to | 2038 | network. The configuration file included in your download is already |
2014 | connect you to the GNUnet network. In this section the relevant configuration | 2039 | configured to connect you to the GNUnet network. |
2015 | settings are explained. | 2040 | In this section the relevant configuration settings are explained. |
2016 | 2041 | ||
2017 | To get an initial connection to the GNUnet network and to get to know peers | 2042 | To get an initial connection to the GNUnet network and to get to know |
2018 | already connected to the network you can use the so called bootstrap servers. | 2043 | peers already connected to the network you can use the so called |
2019 | These servers can give you a list of peers connected to the network. To use | 2044 | bootstrap servers. |
2020 | these bootstrap servers you have to configure the hostlist daemon to activate | 2045 | These servers can give you a list of peers connected to the network. |
2021 | bootstrapping. | 2046 | To use these bootstrap servers you have to configure the hostlist daemon |
2047 | to activate bootstrapping. | ||
2022 | 2048 | ||
2023 | To activate bootstrapping edit your configuration file and edit the | 2049 | To activate bootstrapping edit your configuration file and edit the |
2024 | @code{[hostlist]}-section. You have to set the argument "-b" in the options | 2050 | @code{[hostlist]}-section. You have to set the argument "-b" in the |
2025 | line: | 2051 | options line: |
2052 | |||
2026 | @example | 2053 | @example |
2027 | [hostlist] | 2054 | [hostlist] |
2028 | OPTIONS = -b | 2055 | OPTIONS = -b |
2029 | @end example | 2056 | @end example |
2030 | 2057 | ||
2031 | Additionally you have to specify which server you want to use. The default | 2058 | Additionally you have to specify which server you want to use. |
2032 | bootstrapping server is "@uref{http://v10.gnunet.org/hostlist, | 2059 | The default bootstrapping server is |
2033 | http://v10.gnunet.org/hostlist}". [^] To set the server you have to edit the | 2060 | "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". |
2034 | line "SERVERS" in the hostlist section. To use the default server you should | 2061 | [^] To set the server you have to edit the line "SERVERS" in the hostlist |
2035 | set the lines to | 2062 | section. To use the default server you should set the lines to |
2063 | |||
2036 | @example | 2064 | @example |
2037 | SERVERS = http://v10.gnunet.org/hostlist [^] | 2065 | SERVERS = http://v10.gnunet.org/hostlist [^] |
2038 | @end example | 2066 | @end example |
2039 | 2067 | ||
2040 | 2068 | @noindent | |
2041 | To use bootstrapping your configuration file should include these lines: | 2069 | To use bootstrapping your configuration file should include these lines: |
2070 | |||
2042 | @example | 2071 | @example |
2043 | [hostlist] | 2072 | [hostlist] |
2044 | OPTIONS = -b | 2073 | OPTIONS = -b |
2045 | SERVERS = http://v10.gnunet.org/hostlist [^] | 2074 | SERVERS = http://v10.gnunet.org/hostlist [^] |
2046 | @end example | 2075 | @end example |
2047 | 2076 | ||
2077 | @noindent | ||
2078 | Besides using bootstrap servers you can configure your GNUnet peer to | ||
2079 | recieve hostlist advertisements. | ||
2080 | Peers offering hostlists to other peers can send advertisement messages | ||
2081 | to peers that connect to them. If you configure your peer to receive these | ||
2082 | messages, your peer can download these lists and connect to the peers | ||
2083 | included. These lists are persistent, which means that they are saved to | ||
2084 | your hard disk regularly and are loaded during startup. | ||
2048 | 2085 | ||
2049 | Besides using bootstrap servers you can configure your GNUnet peer to recieve | 2086 | To activate hostlist learning you have to add the "-e" switch to the |
2050 | hostlist advertisements. Peers offering hostlists to other peers can send | 2087 | OPTIONS line in the hostlist section: |
2051 | advertisement messages to peers that connect to them. If you configure your | ||
2052 | peer to receive these messages, your peer can download these lists and connect | ||
2053 | to the peers included. These lists are persistent, which means that they are | ||
2054 | saved to your hard disk regularly and are loaded during startup. | ||
2055 | 2088 | ||
2056 | To activate hostlist learning you have to add the "-e" switch to the OPTIONS | ||
2057 | line in the hostlist section: | ||
2058 | @example | 2089 | @example |
2059 | [hostlist] | 2090 | [hostlist] |
2060 | OPTIONS = -b -e | 2091 | OPTIONS = -b -e |
2061 | @end example | 2092 | @end example |
2062 | 2093 | ||
2063 | 2094 | @noindent | |
2064 | Furthermore you can specify in which file the lists are saved. To save the | 2095 | Furthermore you can specify in which file the lists are saved. To save the |
2065 | lists in the file "hostlists.file" just add the line: | 2096 | lists in the file "hostlists.file" just add the line: |
2097 | |||
2066 | @example | 2098 | @example |
2067 | HOSTLISTFILE = hostlists.file | 2099 | HOSTLISTFILE = hostlists.file |
2068 | @end example | 2100 | @end example |
2069 | 2101 | ||
2102 | @noindent | ||
2103 | Best practice is to activate both bootstrapping and hostlist learning. | ||
2104 | So your configuration file should include these lines: | ||
2070 | 2105 | ||
2071 | Best practice is to activate both bootstrapping and hostlist learning. So your | ||
2072 | configuration file should include these lines: | ||
2073 | @example | 2106 | @example |
2074 | [hostlist] | 2107 | [hostlist] |
2075 | OPTIONS = -b -e | 2108 | OPTIONS = -b -e |
@@ -2081,34 +2114,33 @@ HOSTLISTFILE = $SERVICEHOME/hostlists.file | |||
2081 | @node Configuration of the HOSTLIST proxy settings | 2114 | @node Configuration of the HOSTLIST proxy settings |
2082 | @subsection Configuration of the HOSTLIST proxy settings | 2115 | @subsection Configuration of the HOSTLIST proxy settings |
2083 | 2116 | ||
2084 | The hostlist client can be configured to use a proxy to connect to the hostlist | 2117 | The hostlist client can be configured to use a proxy to connect to the |
2085 | server. This functionality can be configured in the configuration file directly | 2118 | hostlist server. |
2119 | This functionality can be configured in the configuration file directly | ||
2086 | or using the gnunet-setup tool. | 2120 | or using the gnunet-setup tool. |
2087 | 2121 | ||
2088 | The hostlist client supports the following proxy types at the moment: | 2122 | The hostlist client supports the following proxy types at the moment: |
2089 | @itemize @bullet | ||
2090 | 2123 | ||
2091 | 2124 | @itemize @bullet | |
2092 | @item | 2125 | @item HTTP and HTTP 1.0 only proxy |
2093 | HTTP and HTTP 1.0 only proxy | 2126 | @item SOCKS 4/4a/5/5 with hostname |
2094 | |||
2095 | @item | ||
2096 | SOCKS 4/4a/5/5 with hostname | ||
2097 | @end itemize | 2127 | @end itemize |
2098 | 2128 | ||
2099 | |||
2100 | In addition authentication at the proxy with username and password can be | 2129 | In addition authentication at the proxy with username and password can be |
2101 | configured. | 2130 | configured. |
2102 | 2131 | ||
2103 | To configure proxy support for the hostlist client in the gnunet-setup tool, | 2132 | To configure proxy support for the hostlist client in the gnunet-setup |
2104 | select the "hostlist" tab and select the appropriate proxy type. The hostname | 2133 | tool, select the "hostlist" tab and select the appropriate proxy type. |
2105 | or IP address (including port if required) has to be entered in the "Proxy | 2134 | The hostname or IP address (including port if required) has to be entered |
2106 | hostname" textbox. If required, enter username and password in the "Proxy | 2135 | in the "Proxy hostname" textbox. If required, enter username and password |
2107 | username" and "Proxy password" boxes. Be aware that these information will be | 2136 | in the "Proxy username" and "Proxy password" boxes. |
2108 | stored in the configuration in plain text. | 2137 | Be aware that these information will be stored in the configuration in |
2138 | plain text. | ||
2139 | |||
2140 | To configure these options directly in the configuration, you can | ||
2141 | configure the following settings in the | ||
2142 | @code{[hostlist]} section of the configuration: | ||
2109 | 2143 | ||
2110 | To configure these options directly in the configuration, you can configure the | ||
2111 | following settings in the @code{[hostlist]} section of the configuration:@ | ||
2112 | @example | 2144 | @example |
2113 | # Type of proxy server,@ | 2145 | # Type of proxy server,@ |
2114 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@ | 2146 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@ |
@@ -2126,20 +2158,21 @@ following settings in the @code{[hostlist]} section of the configuration:@ | |||
2126 | @node Configuring your peer to provide a hostlist | 2158 | @node Configuring your peer to provide a hostlist |
2127 | @subsection Configuring your peer to provide a hostlist | 2159 | @subsection Configuring your peer to provide a hostlist |
2128 | 2160 | ||
2129 | If you operate a peer permanently connected to GNUnet you can configure your | 2161 | If you operate a peer permanently connected to GNUnet you can configure |
2130 | peer to act as a hostlist server, providing other peers the list of peers known | 2162 | your peer to act as a hostlist server, providing other peers the list of |
2131 | to him. | 2163 | peers known to him. |
2132 | 2164 | ||
2133 | Yor server can act as a bootstrap server and peers needing to obtain a list of | 2165 | Yor server can act as a bootstrap server and peers needing to obtain a |
2134 | peers can contact him to download this list. To download this hostlist the peer | 2166 | list of peers can contact him to download this list. |
2135 | uses HTTP. For this reason you have to build your peer with libcurl and | 2167 | To download this hostlist the peer uses HTTP. |
2136 | microhttpd support. How you build your peer with this options can be found | 2168 | For this reason you have to build your peer with libcurl and microhttpd |
2137 | here: https://gnunet.org/generic_installation | 2169 | support. How you build your peer with this options can be found here: |
2170 | @uref{https://gnunet.org/generic_installation} | ||
2138 | 2171 | ||
2139 | To configure your peer to act as a bootstrap server you have to add the "-p" | 2172 | To configure your peer to act as a bootstrap server you have to add the |
2140 | option to OPTIONS in the [hostlist] section of your configuration file. Besides | 2173 | "@code{-p}" option to OPTIONS in the @code{[hostlist]} section of your |
2141 | that you have to specify a port number for the http server. In conclusion you | 2174 | configuration file. Besides that you have to specify a port number for |
2142 | have to add the following lines: | 2175 | the http server. In conclusion you have to add the following lines: |
2143 | 2176 | ||
2144 | @example | 2177 | @example |
2145 | [hostlist] | 2178 | [hostlist] |
@@ -2147,16 +2180,18 @@ HTTPPORT = 12980 | |||
2147 | OPTIONS = -p | 2180 | OPTIONS = -p |
2148 | @end example | 2181 | @end example |
2149 | 2182 | ||
2183 | @noindent | ||
2184 | If your peer acts as a bootstrap server other peers should know about | ||
2185 | that. You can advertise the hostlist your are providing to other peers. | ||
2186 | Peers connecting to your peer will get a message containing an | ||
2187 | advertisement for your hostlist and the URL where it can be downloaded. | ||
2188 | If this peer is in learning mode, it will test the hostlist and, in the | ||
2189 | case it can obtain the list successfully, it will save it for | ||
2190 | bootstrapping. | ||
2150 | 2191 | ||
2151 | If your peer acts as a bootstrap server other peers should know about that. You | 2192 | To activate hostlist advertisement on your peer, you have to set the |
2152 | can advertise the hostlist your are providing to other peers. Peers connecting | 2193 | following lines in your configuration file: |
2153 | to your peer will get a message containing an advertisement for your hostlist | ||
2154 | and the URL where it can be downloaded. If this peer is in learning mode, it | ||
2155 | will test the hostlist and, in the case it can obtain the list successfully, it | ||
2156 | will save it for bootstrapping. | ||
2157 | 2194 | ||
2158 | To activate hostlist advertisement on your peer, you have to set the following | ||
2159 | lines in your configuration file: | ||
2160 | @example | 2195 | @example |
2161 | [hostlist] | 2196 | [hostlist] |
2162 | EXTERNAL_DNS_NAME = example.org | 2197 | EXTERNAL_DNS_NAME = example.org |
@@ -2164,47 +2199,44 @@ HTTPPORT = 12981 | |||
2164 | OPTIONS = -p -a | 2199 | OPTIONS = -p -a |
2165 | @end example | 2200 | @end example |
2166 | 2201 | ||
2167 | 2202 | @noindent | |
2168 | With this configuration your peer will a act as a bootstrap server and | 2203 | With this configuration your peer will a act as a bootstrap server and |
2169 | advertise this hostlist to other peers connecting to him. The URL used to | 2204 | advertise this hostlist to other peers connecting to him. The URL used to |
2170 | download the list will be @code{@uref{http://example.org:12981/, | 2205 | download the list will be |
2171 | http://example.org:12981/}}. | 2206 | @code{@uref{http://example.org:12981/, http://example.org:12981/}}. |
2172 | 2207 | ||
2173 | Please notice: | 2208 | Please notice: |
2174 | @itemize @bullet | 2209 | @itemize @bullet |
2175 | 2210 | @item The hostlist is not human readable, so you should not try to | |
2176 | 2211 | download it using your webbrowser. Just point your GNUnet peer to the | |
2177 | @item | 2212 | address! |
2178 | The hostlist is not human readable, so you should not try to download it using | 2213 | @item Advertising without providing a hostlist does not make sense and |
2179 | your webbrowser. Just point your GNUnet peer to the address! | 2214 | will not work. |
2180 | |||
2181 | @item | ||
2182 | Advertising without providing a hostlist does not make sense and will not work. | ||
2183 | @end itemize | 2215 | @end itemize |
2184 | 2216 | ||
2185 | @node Configuring the datastore | 2217 | @node Configuring the datastore |
2186 | @subsection Configuring the datastore | 2218 | @subsection Configuring the datastore |
2187 | 2219 | ||
2188 | The datastore is what GNUnet uses to for long-term storage of file-sharing | 2220 | The datastore is what GNUnet uses to for long-term storage of file-sharing |
2189 | data. Note that long-term does not mean 'forever' since content does have an | 2221 | data. Note that long-term does not mean 'forever' since content does have |
2190 | expiration date, and of course storage space is finite (and hence sometimes | 2222 | an expiration date, and of course storage space is finite (and hence |
2191 | content may have to be discarded). | 2223 | sometimes content may have to be discarded). |
2192 | 2224 | ||
2193 | Use the "QUOTA" option to specify how many bytes of storage space you are | 2225 | Use the "QUOTA" option to specify how many bytes of storage space you are |
2194 | willing to dedicate to GNUnet. | 2226 | willing to dedicate to GNUnet. |
2195 | 2227 | ||
2196 | In addition to specifying the maximum space GNUnet is allowed to use for the | 2228 | In addition to specifying the maximum space GNUnet is allowed to use for |
2197 | datastore, you need to specify which database GNUnet should use to do so. | 2229 | the datastore, you need to specify which database GNUnet should use to do |
2198 | Currently, you have the choice between sqLite, MySQL and Postgres. | 2230 | so. Currently, you have the choice between sqLite, MySQL and Postgres. |
2199 | 2231 | ||
2200 | @node Configuring the MySQL database | 2232 | @node Configuring the MySQL database |
2201 | @subsection Configuring the MySQL database | 2233 | @subsection Configuring the MySQL database |
2202 | 2234 | ||
2203 | This section describes how to setup the MySQL database for GNUnet. | 2235 | This section describes how to setup the MySQL database for GNUnet. |
2204 | 2236 | ||
2205 | Note that the mysql plugin does NOT work with mysql before 4.1 since we need | 2237 | Note that the mysql plugin does NOT work with mysql before 4.1 since we |
2206 | prepared statements. We are generally testing the code against MySQL 5.1 at | 2238 | need prepared statements. |
2207 | this point. | 2239 | We are generally testing the code against MySQL 5.1 at this point. |
2208 | 2240 | ||
2209 | @node Reasons for using MySQL | 2241 | @node Reasons for using MySQL |
2210 | @subsection Reasons for using MySQL | 2242 | @subsection Reasons for using MySQL |
@@ -2212,9 +2244,9 @@ this point. | |||
2212 | @itemize @bullet | 2244 | @itemize @bullet |
2213 | 2245 | ||
2214 | @item | 2246 | @item |
2215 | On up-to-date hardware where mysql can be used comfortably, this module will | 2247 | On up-to-date hardware where mysql can be used comfortably, this module |
2216 | have better performance than the other database choices (according to our | 2248 | will have better performance than the other database choices (according |
2217 | tests). | 2249 | to our tests). |
2218 | 2250 | ||
2219 | @item Its often possible to recover the mysql database from internal | 2251 | @item Its often possible to recover the mysql database from internal |
2220 | inconsistencies. Some of the other databases do not support repair. | 2252 | inconsistencies. Some of the other databases do not support repair. |
@@ -2224,33 +2256,26 @@ inconsistencies. Some of the other databases do not support repair. | |||
2224 | @subsection Reasons for not using MySQL | 2256 | @subsection Reasons for not using MySQL |
2225 | 2257 | ||
2226 | @itemize @bullet | 2258 | @itemize @bullet |
2227 | 2259 | @item Memory usage (likely not an issue if you have more than 1 GB) | |
2228 | @item | 2260 | @item Complex manual setup |
2229 | Memory usage (likely not an issue if you have more than 1 GB) | ||
2230 | |||
2231 | @item | ||
2232 | Complex manual setup | ||
2233 | @end itemize | 2261 | @end itemize |
2234 | 2262 | ||
2235 | @node Setup Instructions | 2263 | @node Setup Instructions |
2236 | @subsection Setup Instructions | 2264 | @subsection Setup Instructions |
2237 | 2265 | ||
2238 | @itemize @bullet | 2266 | @itemize @bullet |
2239 | 2267 | @item In @code{gnunet.conf} set in section "DATASTORE" the value for | |
2240 | @item | 2268 | "DATABASE" to "mysql". |
2241 | In @code{gnunet.conf} set in section "DATASTORE" the value for "DATABASE" to | 2269 | @item Access mysql as root:@ |
2242 | "mysql". | ||
2243 | |||
2244 | @item | ||
2245 | Access mysql as root:@ | ||
2246 | 2270 | ||
2247 | @example | 2271 | @example |
2248 | $ mysql -u root -p | 2272 | $ mysql -u root -p |
2249 | @end example | 2273 | @end example |
2250 | 2274 | ||
2275 | @noindent | ||
2276 | and issue the following commands, replacing $USER with the username | ||
2277 | that will be running gnunet-arm (so typically "gnunet"): | ||
2251 | 2278 | ||
2252 | and issue the following commands, replacing $USER with the username@ | ||
2253 | that will be running gnunet-arm (so typically "gnunet"): | ||
2254 | @example | 2279 | @example |
2255 | CREATE DATABASE gnunet; | 2280 | CREATE DATABASE gnunet; |
2256 | GRANT select,insert,update,delete,create,alter,drop,create temporary tables | 2281 | GRANT select,insert,update,delete,create,alter,drop,create temporary tables |
@@ -2259,9 +2284,9 @@ SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); | |||
2259 | FLUSH PRIVILEGES; | 2284 | FLUSH PRIVILEGES; |
2260 | @end example | 2285 | @end example |
2261 | 2286 | ||
2262 | |||
2263 | @item | 2287 | @item |
2264 | In the $HOME directory of $USER, create a ".my.cnf" file with the following lines@ | 2288 | In the $HOME directory of $USER, create a ".my.cnf" file with the |
2289 | following lines | ||
2265 | 2290 | ||
2266 | @example | 2291 | @example |
2267 | [client] | 2292 | [client] |
@@ -2271,90 +2296,87 @@ password=$the_password_you_like | |||
2271 | 2296 | ||
2272 | @end itemize | 2297 | @end itemize |
2273 | 2298 | ||
2299 | Thats it. Note that @code{.my.cnf} file is a slight security risk unless | ||
2300 | its on a safe partition. The $HOME/.my.cnf can of course be a symbolic | ||
2301 | link. Luckily $USER has only priviledges to mess up GNUnet's tables, | ||
2302 | which should be pretty harmless. | ||
2274 | 2303 | ||
2275 | Thats it. Note that @code{.my.cnf} file is a slight security risk unless its | ||
2276 | on@ a safe partition. The $HOME/.my.cnf can of course be a symbolic@ link. | ||
2277 | Luckily $USER has only priviledges to mess up GNUnet's tables, which should be | ||
2278 | pretty harmless. | ||
2279 | @node Testing | 2304 | @node Testing |
2280 | @subsection Testing | 2305 | @subsection Testing |
2281 | 2306 | ||
2282 | You should briefly try if the database connection works. First, login as $USER. | 2307 | You should briefly try if the database connection works. First, login |
2283 | Then use: | 2308 | as $USER. Then use: |
2309 | |||
2284 | @example | 2310 | @example |
2285 | $ mysql -u $USER | 2311 | $ mysql -u $USER |
2286 | mysql> use gnunet; | 2312 | mysql> use gnunet; |
2287 | @end example | 2313 | @end example |
2288 | 2314 | ||
2289 | 2315 | @noindent | |
2290 | If you get the message "Database changed" it probably works. | 2316 | If you get the message "Database changed" it probably works. |
2291 | 2317 | ||
2292 | If you get "ERROR 2002: Can't connect to local MySQL server@ | 2318 | If you get "ERROR 2002: Can't connect to local MySQL server@ |
2293 | through socket '/tmp/mysql.sock' (2)" it may be resolvable by@ | 2319 | through socket '/tmp/mysql.sock' (2)" it may be resolvable by@ |
2294 | "ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock"@ | 2320 | "ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock"@ |
2295 | so there may be some additional trouble depending on your mysql setup. | 2321 | so there may be some additional trouble depending on your mysql setup. |
2322 | |||
2296 | @node Performance Tuning | 2323 | @node Performance Tuning |
2297 | @subsection Performance Tuning | 2324 | @subsection Performance Tuning |
2298 | 2325 | ||
2299 | For GNUnet, you probably want to set the option | 2326 | For GNUnet, you probably want to set the option |
2327 | |||
2300 | @example | 2328 | @example |
2301 | innodb_flush_log_at_trx_commit = 0 | 2329 | innodb_flush_log_at_trx_commit = 0 |
2302 | @end example | 2330 | @end example |
2303 | 2331 | ||
2304 | for a rather dramatic boost in MySQL performance. However, this reduces the | 2332 | @noindent |
2305 | "safety" of your database as with this options you may loose transactions | 2333 | for a rather dramatic boost in MySQL performance. However, this reduces |
2306 | during a power outage. While this is totally harmless for GNUnet, the option | 2334 | the "safety" of your database as with this options you may loose |
2307 | applies to all applications using MySQL. So you should set it if (and only if) | 2335 | transactions during a power outage. |
2308 | GNUnet is the only application on your system using MySQL. | 2336 | While this is totally harmless for GNUnet, the option applies to all |
2337 | applications using MySQL. So you should set it if (and only if) GNUnet is | ||
2338 | the only application on your system using MySQL. | ||
2309 | 2339 | ||
2310 | @node Setup for running Testcases | 2340 | @node Setup for running Testcases |
2311 | @subsection Setup for running Testcases | 2341 | @subsection Setup for running Testcases |
2312 | 2342 | ||
2313 | If you want to run the testcases, you must create a second database | 2343 | If you want to run the testcases, you must create a second database |
2314 | "gnunetcheck" with the same username and password. This database will then be | 2344 | "gnunetcheck" with the same username and password. This database will |
2315 | used for testing ("make check"). | 2345 | then be used for testing ("make check"). |
2316 | 2346 | ||
2317 | @node Configuring the Postgres database | 2347 | @node Configuring the Postgres database |
2318 | @subsection Configuring the Postgres database | 2348 | @subsection Configuring the Postgres database |
2319 | 2349 | ||
2320 | This text describes how to setup the Postgres database for GNUnet. | 2350 | This text describes how to setup the Postgres database for GNUnet. |
2321 | 2351 | ||
2322 | This Postgres plugin was developed for Postgres 8.3 but might work for earlier | 2352 | This Postgres plugin was developed for Postgres 8.3 but might work for |
2323 | versions as well. | 2353 | earlier versions as well. |
2324 | 2354 | ||
2325 | @node Reasons to use Postgres | 2355 | @node Reasons to use Postgres |
2326 | @subsection Reasons to use Postgres | 2356 | @subsection Reasons to use Postgres |
2327 | 2357 | ||
2328 | @itemize @bullet | 2358 | @itemize @bullet |
2329 | @item | 2359 | @item Easier to setup than MySQL |
2330 | Easier to setup than MySQL | 2360 | @item Real database |
2331 | @item | ||
2332 | Real database | ||
2333 | @end itemize | 2361 | @end itemize |
2334 | 2362 | ||
2335 | @node Reasons not to use Postgres | 2363 | @node Reasons not to use Postgres |
2336 | @subsection Reasons not to use Postgres | 2364 | @subsection Reasons not to use Postgres |
2337 | 2365 | ||
2338 | @itemize @bullet | 2366 | @itemize @bullet |
2339 | @item | 2367 | @item Quite slow |
2340 | Quite slow | 2368 | @item Still some manual setup required |
2341 | @item | ||
2342 | Still some manual setup required | ||
2343 | @end itemize | 2369 | @end itemize |
2344 | 2370 | ||
2345 | @node Manual setup instructions | 2371 | @node Manual setup instructions |
2346 | @subsection Manual setup instructions | 2372 | @subsection Manual setup instructions |
2347 | 2373 | ||
2348 | @itemize @bullet | 2374 | @itemize @bullet |
2349 | 2375 | @item In @code{gnunet.conf} set in section "DATASTORE" the value for | |
2350 | @item | ||
2351 | In @code{gnunet.conf} set in section "DATASTORE" the value for@ | ||
2352 | "DATABASE" to "postgres". | 2376 | "DATABASE" to "postgres". |
2353 | @item | 2377 | @item Access Postgres to create a user:@ |
2354 | Access Postgres to create a user:@ | ||
2355 | 2378 | ||
2356 | @table @asis | 2379 | @table @asis |
2357 | |||
2358 | @item with Postgres 8.x, use: | 2380 | @item with Postgres 8.x, use: |
2359 | 2381 | ||
2360 | @example | 2382 | @example |
@@ -2362,6 +2384,7 @@ Access Postgres to create a user:@ | |||
2362 | $ createuser | 2384 | $ createuser |
2363 | @end example | 2385 | @end example |
2364 | 2386 | ||
2387 | @noindent | ||
2365 | and enter the name of the user running GNUnet for the role interactively. | 2388 | and enter the name of the user running GNUnet for the role interactively. |
2366 | Then, when prompted, do not set it to superuser, allow the creation of | 2389 | Then, when prompted, do not set it to superuser, allow the creation of |
2367 | databases, and do not allow the creation of new roles.@ | 2390 | databases, and do not allow the creation of new roles.@ |
@@ -2373,7 +2396,7 @@ databases, and do not allow the creation of new roles.@ | |||
2373 | $ createuser -d $GNUNET_USER | 2396 | $ createuser -d $GNUNET_USER |
2374 | @end example | 2397 | @end example |
2375 | 2398 | ||
2376 | 2399 | @noindent | |
2377 | where $GNUNET_USER is the name of the user running GNUnet.@ | 2400 | where $GNUNET_USER is the name of the user running GNUnet.@ |
2378 | 2401 | ||
2379 | @end table | 2402 | @end table |
@@ -2384,105 +2407,116 @@ As that user (so typically as user "gnunet"), create a database (or two):@ | |||
2384 | 2407 | ||
2385 | @example | 2408 | @example |
2386 | $ createdb gnunet | 2409 | $ createdb gnunet |
2387 | $ createdb gnunetcheck # this way you can run "make check" | 2410 | # this way you can run "make check" |
2411 | $ createdb gnunetcheck | ||
2388 | @end example | 2412 | @end example |
2389 | 2413 | ||
2390 | @end itemize | 2414 | @end itemize |
2391 | 2415 | ||
2392 | |||
2393 | Now you should be able to start @code{gnunet-arm}. | 2416 | Now you should be able to start @code{gnunet-arm}. |
2394 | 2417 | ||
2395 | @node Testing the setup manually | 2418 | @node Testing the setup manually |
2396 | @subsection Testing the setup manually | 2419 | @subsection Testing the setup manually |
2397 | 2420 | ||
2398 | You may want to try if the database connection works. First, again login as | 2421 | You may want to try if the database connection works. First, again login |
2399 | the user who will run gnunet-arm. Then use, | 2422 | as the user who will run gnunet-arm. Then use, |
2423 | |||
2400 | @example | 2424 | @example |
2401 | $ psql gnunet # or gnunetcheck | 2425 | $ psql gnunet # or gnunetcheck |
2402 | gnunet=> \dt | 2426 | gnunet=> \dt |
2403 | @end example | 2427 | @end example |
2404 | 2428 | ||
2405 | 2429 | @noindent | |
2406 | If, after you have started gnunet-arm at least once, you get a @code{gn090} | 2430 | If, after you have started gnunet-arm at least once, you get |
2407 | table here, it probably works. | 2431 | a @code{gn090} table here, it probably works. |
2408 | 2432 | ||
2409 | @node Configuring the datacache | 2433 | @node Configuring the datacache |
2410 | @subsection Configuring the datacache | 2434 | @subsection Configuring the datacache |
2411 | @c %**end of header | 2435 | @c %**end of header |
2412 | 2436 | ||
2413 | The datacache is what GNUnet uses for storing temporary data. This data is | 2437 | The datacache is what GNUnet uses for storing temporary data. This data is |
2414 | expected to be wiped completely each time GNUnet is restarted (or the system | 2438 | expected to be wiped completely each time GNUnet is restarted (or the |
2415 | is rebooted). | 2439 | system is rebooted). |
2416 | 2440 | ||
2417 | You need to specify how many bytes GNUnet is allowed to use for the datacache | 2441 | You need to specify how many bytes GNUnet is allowed to use for the |
2418 | using the "QUOTA" option in the section "dhtcache". Furthermore, you need to | 2442 | datacache using the "QUOTA" option in the section "dhtcache". |
2419 | specify which database backend should be used to store the data. Currently, | 2443 | Furthermore, you need to specify which database backend should be used to |
2420 | you have the choice between sqLite, MySQL and Postgres. | 2444 | store the data. Currently, you have the choice between |
2445 | sqLite, MySQL and Postgres. | ||
2421 | 2446 | ||
2422 | @node Configuring the file-sharing service | 2447 | @node Configuring the file-sharing service |
2423 | @subsection Configuring the file-sharing service | 2448 | @subsection Configuring the file-sharing service |
2424 | 2449 | ||
2425 | In order to use GNUnet for file-sharing, you first need to make sure that the | 2450 | In order to use GNUnet for file-sharing, you first need to make sure |
2426 | file-sharing service is loaded. This is done by setting the AUTOSTART option in | 2451 | that the file-sharing service is loaded. |
2427 | section "fs" to "YES". Alternatively, you can run | 2452 | This is done by setting the AUTOSTART option in section "fs" to "YES". |
2453 | Alternatively, you can run | ||
2454 | |||
2428 | @example | 2455 | @example |
2429 | $ gnunet-arm -i fs | 2456 | $ gnunet-arm -i fs |
2430 | @end example | 2457 | @end example |
2431 | 2458 | ||
2459 | @noindent | ||
2432 | to start the file-sharing service by hand. | 2460 | to start the file-sharing service by hand. |
2433 | 2461 | ||
2434 | Except for configuring the database and the datacache the only important option | 2462 | Except for configuring the database and the datacache the only important |
2435 | for file-sharing is content migration. | 2463 | option for file-sharing is content migration. |
2436 | 2464 | ||
2437 | Content migration allows your peer to cache content from other peers as well as | 2465 | Content migration allows your peer to cache content from other peers as |
2438 | send out content stored on your system without explicit requests. This content | 2466 | well as send out content stored on your system without explicit requests. |
2439 | replication has positive and negative impacts on both system performance an | 2467 | This content replication has positive and negative impacts on both system |
2440 | privacy. | 2468 | performance and privacy. |
2441 | 2469 | ||
2442 | FIXME: discuss the trade-offs. Here is some older text about it... | 2470 | FIXME: discuss the trade-offs. Here is some older text about it... |
2443 | 2471 | ||
2444 | Setting this option to YES allows gnunetd to migrate data to the local machine. | 2472 | Setting this option to YES allows gnunetd to migrate data to the local |
2445 | Setting this option to YES is highly recommended for efficiency. Its also the | 2473 | machine. Setting this option to YES is highly recommended for efficiency. |
2446 | default. If you set this value to YES, GNUnet will store content on your | 2474 | Its also the default. If you set this value to YES, GNUnet will store |
2447 | machine that you cannot decrypt. While this may protect you from liability if | 2475 | content on your machine that you cannot decrypt. |
2448 | the judge is sane, it may not (IANAL). If you put illegal content on your | 2476 | While this may protect you from liability if the judge is sane, it may |
2449 | machine yourself, setting this option to YES will probably increase your chances | 2477 | not (IANAL). If you put illegal content on your machine yourself, setting |
2450 | to get away with it since you can plausibly deny that you inserted the content. | 2478 | this option to YES will probably increase your chances to get away with it |
2451 | Note that in either case, your anonymity would have to be broken first (which | 2479 | since you can plausibly deny that you inserted the content. |
2452 | may be possible depending on the size of the GNUnet network and the strength of | 2480 | Note that in either case, your anonymity would have to be broken first |
2453 | the adversary). | 2481 | (which may be possible depending on the size of the GNUnet network and the |
2482 | strength of the adversary). | ||
2454 | 2483 | ||
2455 | @node Configuring logging | 2484 | @node Configuring logging |
2456 | @subsection Configuring logging | 2485 | @subsection Configuring logging |
2457 | 2486 | ||
2458 | Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. | 2487 | Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. |
2459 | Using "-L", a log level can be specified. With log level "ERROR" only serious | 2488 | Using "-L", a log level can be specified. With log level "ERROR" only |
2460 | errors are logged. The default log level is "WARNING" which causes anything of | 2489 | serious errors are logged. |
2461 | concern to be logged. Log level "INFO" can be used to log anything that might | 2490 | The default log level is "WARNING" which causes anything of |
2462 | be interesting information whereas "DEBUG" can be used by developers to log | 2491 | concern to be logged. Log level "INFO" can be used to log anything that |
2463 | debugging messages (but you need to run configure with | 2492 | might be interesting information whereas "DEBUG" can be used by |
2464 | @code{--enable-logging=verbose} to get them compiled). The "-l" option is used | 2493 | developers to log debugging messages (but you need to run configure with |
2465 | to specify the log file. | 2494 | @code{--enable-logging=verbose} to get them compiled). |
2466 | 2495 | The "-l" option is used to specify the log file. | |
2467 | Since most GNUnet services are managed by @code{gnunet-arm}, using the "-l" or | 2496 | |
2468 | "-L" options directly is not possible. Instead, they can be specified using the | 2497 | Since most GNUnet services are managed by @code{gnunet-arm}, using the |
2469 | "OPTIONS" configuration value in the respective section for the respective | 2498 | "-l" or "-L" options directly is not possible. |
2470 | service. In order to enable logging globally without editing the "OPTIONS" | 2499 | Instead, they can be specified using the "OPTIONS" configuration value in |
2471 | values for each service, @code{gnunet-arm} supports a "GLOBAL_POSTFIX" option. | 2500 | the respective section for the respective service. |
2472 | The value specified here is given as an extra option to all services for which | 2501 | In order to enable logging globally without editing the "OPTIONS" values |
2473 | the configuration does contain a service-specific "OPTIONS" field. | 2502 | for each service, @code{gnunet-arm} supports a "GLOBAL_POSTFIX" option. |
2474 | 2503 | The value specified here is given as an extra option to all services for | |
2475 | "GLOBAL_POSTFIX" can contain the special sequence "@{@}" which is replaced by | 2504 | which the configuration does contain a service-specific "OPTIONS" field. |
2476 | the name of the service that is being started. Furthermore, | 2505 | |
2477 | @code{GLOBAL_POSTFIX} is special in that sequences starting with "$" anywhere | 2506 | "GLOBAL_POSTFIX" can contain the special sequence "@{@}" which is replaced |
2478 | in the string are expanded (according to options in "PATHS"); this expansion | 2507 | by the name of the service that is being started. Furthermore, |
2479 | otherwise is only happening for filenames and then the "$" must be the first | 2508 | @code{GLOBAL_POSTFIX} is special in that sequences starting with "$" |
2480 | character in the option. Both of these restrictions do not apply to | 2509 | anywhere in the string are expanded (according to options in "PATHS"); |
2481 | "GLOBAL_POSTFIX". Note that specifying @code{%} anywhere in the "GLOBAL_POSTFIX" | 2510 | this expansion otherwise is only happening for filenames and then the "$" |
2482 | disables both of these features. | 2511 | must be the first character in the option. Both of these restrictions do |
2483 | 2512 | not apply to "GLOBAL_POSTFIX". | |
2484 | In summary, in order to get all services to log at level "INFO" to log-files | 2513 | Note that specifying @code{%} anywhere in the "GLOBAL_POSTFIX" disables |
2485 | called @code{SERVICENAME-logs}, the following global prefix should be used: | 2514 | both of these features. |
2515 | |||
2516 | In summary, in order to get all services to log at level "INFO" to | ||
2517 | log-files called @code{SERVICENAME-logs}, the following global prefix | ||
2518 | should be used: | ||
2519 | |||
2486 | @example | 2520 | @example |
2487 | GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO | 2521 | GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO |
2488 | @end example | 2522 | @end example |
@@ -2490,17 +2524,18 @@ GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO | |||
2490 | @node Configuring the transport service and plugins | 2524 | @node Configuring the transport service and plugins |
2491 | @subsection Configuring the transport service and plugins | 2525 | @subsection Configuring the transport service and plugins |
2492 | 2526 | ||
2493 | The transport service in GNUnet is responsible to maintain basic connectivity | 2527 | The transport service in GNUnet is responsible to maintain basic |
2494 | to other peers. Besides initiating and keeping connections alive it is also | 2528 | connectivity to other peers. |
2495 | responsible for address validation. | 2529 | Besides initiating and keeping connections alive it is also responsible |
2530 | for address validation. | ||
2496 | 2531 | ||
2497 | The GNUnet transport supports more than one transport protocol. These protocols | 2532 | The GNUnet transport supports more than one transport protocol. |
2498 | are configured together with the transport service. | 2533 | These protocols are configured together with the transport service. |
2499 | 2534 | ||
2500 | The configuration section for the transport service itself is quite similar to | 2535 | The configuration section for the transport service itself is quite |
2501 | all the other services | 2536 | similar to all the other services |
2502 | 2537 | ||
2503 | @code{@ | 2538 | @example |
2504 | AUTOSTART = YES@ | 2539 | AUTOSTART = YES@ |
2505 | @@UNIXONLY@@ PORT = 2091@ | 2540 | @@UNIXONLY@@ PORT = 2091@ |
2506 | HOSTNAME = localhost@ | 2541 | HOSTNAME = localhost@ |
@@ -2513,32 +2548,27 @@ all the other services | |||
2513 | ACCEPT_FROM6 = ::1;@ | 2548 | ACCEPT_FROM6 = ::1;@ |
2514 | PLUGINS = tcp udp@ | 2549 | PLUGINS = tcp udp@ |
2515 | UNIXPATH = /tmp/gnunet-service-transport.sock@ | 2550 | UNIXPATH = /tmp/gnunet-service-transport.sock@ |
2516 | } | 2551 | @end example |
2517 | |||
2518 | Different are the settings for the plugins to load @code{PLUGINS}. The first | ||
2519 | setting specifies which transport plugins to load. | ||
2520 | @itemize @bullet | ||
2521 | |||
2522 | 2552 | ||
2523 | @item | 2553 | Different are the settings for the plugins to load @code{PLUGINS}. |
2524 | transport-unix | 2554 | The first setting specifies which transport plugins to load. |
2525 | 2555 | ||
2556 | @itemize @bullet | ||
2557 | @item transport-unix | ||
2526 | A plugin for local only communication with UNIX domain sockets. Used for | 2558 | A plugin for local only communication with UNIX domain sockets. Used for |
2527 | testing and available on unix systems only. Just set the port | 2559 | testing and available on unix systems only. Just set the port |
2528 | 2560 | ||
2529 | @code{@ | 2561 | @example |
2530 | [transport-unix]@ | 2562 | [transport-unix]@ |
2531 | PORT = 22086@ | 2563 | PORT = 22086@ |
2532 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2564 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2533 | } | 2565 | @end example |
2534 | |||
2535 | @item | ||
2536 | transport-tcp | ||
2537 | 2566 | ||
2567 | @item transport-tcp | ||
2538 | A plugin for communication with TCP. Set port to 0 for client mode with | 2568 | A plugin for communication with TCP. Set port to 0 for client mode with |
2539 | outbound only connections | 2569 | outbound only connections |
2540 | 2570 | ||
2541 | @code{@ | 2571 | @example |
2542 | [transport-tcp]@ | 2572 | [transport-tcp]@ |
2543 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding)@ | 2573 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding)@ |
2544 | PORT = 2086@ | 2574 | PORT = 2086@ |
@@ -2546,54 +2576,58 @@ outbound only connections | |||
2546 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2576 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2547 | # Maximum number of open TCP connections allowed@ | 2577 | # Maximum number of open TCP connections allowed@ |
2548 | MAX_CONNECTIONS = 128@ | 2578 | MAX_CONNECTIONS = 128@ |
2549 | } | 2579 | @end example |
2550 | 2580 | ||
2551 | @item | 2581 | @item transport-udp |
2552 | transport-udp | 2582 | A plugin for communication with UDP. Supports peer discovery using |
2583 | broadcasts. | ||
2553 | 2584 | ||
2554 | A plugin for communication with UDP. Supports peer discovery using broadcasts.@ | 2585 | @example |
2555 | @code{@ | ||
2556 | [transport-udp]@ | 2586 | [transport-udp]@ |
2557 | PORT = 2086@ | 2587 | PORT = 2086@ |
2558 | BROADCAST = YES@ | 2588 | BROADCAST = YES@ |
2559 | BROADCAST_INTERVAL = 30 s@ | 2589 | BROADCAST_INTERVAL = 30 s@ |
2560 | MAX_BPS = 1000000@ | 2590 | MAX_BPS = 1000000@ |
2561 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2591 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2562 | } | 2592 | @end example |
2563 | |||
2564 | @item | ||
2565 | transport-http | ||
2566 | 2593 | ||
2594 | @item transport-http | ||
2567 | HTTP and HTTPS support is split in two part: a client plugin initiating | 2595 | HTTP and HTTPS support is split in two part: a client plugin initiating |
2568 | outbound connections and a server part accepting connections from the client. | 2596 | outbound connections and a server part accepting connections from the |
2569 | The client plugin just takes the maximum number of connections as an argument.@ | 2597 | client. The client plugin just takes the maximum number of connections as |
2570 | @code{@ | 2598 | an argument. |
2599 | |||
2600 | @example | ||
2571 | [transport-http_client]@ | 2601 | [transport-http_client]@ |
2572 | MAX_CONNECTIONS = 128@ | 2602 | MAX_CONNECTIONS = 128@ |
2573 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2603 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2574 | }@ | 2604 | @end example |
2575 | @code{@ | 2605 | |
2606 | @example | ||
2576 | [transport-https_client]@ | 2607 | [transport-https_client]@ |
2577 | MAX_CONNECTIONS = 128@ | 2608 | MAX_CONNECTIONS = 128@ |
2578 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2609 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2579 | } | 2610 | @end example |
2580 | 2611 | ||
2581 | The server has a port configured and the maximum nunber of connections.@ | 2612 | @noindent |
2582 | The HTTPS part has two files with the certificate key and the certificate file. | 2613 | The server has a port configured and the maximum nunber of connections. |
2614 | The HTTPS part has two files with the certificate key and the certificate | ||
2615 | file. | ||
2583 | 2616 | ||
2584 | The server plugin supports reverse proxies, so a external hostname can be set | 2617 | The server plugin supports reverse proxies, so a external hostname can be |
2585 | using@ | 2618 | set using the @code{EXTERNAL_HOSTNAME} setting. |
2586 | the @code{EXTERNAL_HOSTNAME} setting. The webserver under this address should | 2619 | The webserver under this address should forward the request to the peer |
2587 | forward the request to the peer and the configure port. | 2620 | and the configure port. |
2588 | 2621 | ||
2589 | @code{@ | 2622 | @example |
2590 | [transport-http_server]@ | 2623 | [transport-http_server]@ |
2591 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet@ | 2624 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet@ |
2592 | PORT = 1080@ | 2625 | PORT = 1080@ |
2593 | MAX_CONNECTIONS = 128@ | 2626 | MAX_CONNECTIONS = 128@ |
2594 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2627 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2595 | }@ | 2628 | @end example |
2596 | @code{@ | 2629 | |
2630 | @example | ||
2597 | [transport-https_server]@ | 2631 | [transport-https_server]@ |
2598 | PORT = 4433@ | 2632 | PORT = 4433@ |
2599 | CRYPTO_INIT = NORMAL@ | 2633 | CRYPTO_INIT = NORMAL@ |
@@ -2601,32 +2635,33 @@ forward the request to the peer and the configure port. | |||
2601 | CERT_FILE = https.cert@ | 2635 | CERT_FILE = https.cert@ |
2602 | MAX_CONNECTIONS = 128@ | 2636 | MAX_CONNECTIONS = 128@ |
2603 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2637 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2604 | } | 2638 | @end example |
2605 | 2639 | ||
2606 | @item | 2640 | @item transport-wlan |
2607 | transport-wlan | ||
2608 | 2641 | ||
2609 | There is a special article how to setup the WLAN plugin, so here only the | 2642 | There is a special article how to setup the WLAN plugin, so here only the |
2610 | settings. Just specify the interface to use:@ | 2643 | settings. Just specify the interface to use: |
2611 | @code{@ | 2644 | |
2645 | @example | ||
2612 | [transport-wlan]@ | 2646 | [transport-wlan]@ |
2613 | # Name of the interface in monitor mode (typically monX)@ | 2647 | # Name of the interface in monitor mode (typically monX)@ |
2614 | INTERFACE = mon0@ | 2648 | INTERFACE = mon0@ |
2615 | # Real hardware, no testing@ | 2649 | # Real hardware, no testing@ |
2616 | TESTMODE = 0@ | 2650 | TESTMODE = 0@ |
2617 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2651 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ |
2618 | } | 2652 | @end example |
2619 | @end itemize | 2653 | @end itemize |
2620 | 2654 | ||
2621 | @node Configuring the wlan transport plugin | 2655 | @node Configuring the wlan transport plugin |
2622 | @subsection Configuring the wlan transport plugin | 2656 | @subsection Configuring the wlan transport plugin |
2623 | 2657 | ||
2624 | 2658 | ||
2625 | The wlan transport plugin enables GNUnet to send and to receive data on a wlan | 2659 | The wlan transport plugin enables GNUnet to send and to receive data on a |
2626 | interface. It has not to be connected to a wlan network as long as sender and | 2660 | wlan interface. |
2627 | receiver are on the same channel. This enables you to get connection to the | 2661 | It has not to be connected to a wlan network as long as sender and |
2628 | GNUnet where no internet access is possible, for example while catastrophes or | 2662 | receiver are on the same channel. This enables you to get connection to |
2629 | when censorship cuts you off the internet. | 2663 | the GNUnet where no internet access is possible, for example while |
2664 | catastrophes or when censorship cuts you off the internet. | ||
2630 | 2665 | ||
2631 | 2666 | ||
2632 | @menu | 2667 | @menu |
@@ -2642,26 +2677,24 @@ when censorship cuts you off the internet. | |||
2642 | 2677 | ||
2643 | @itemize @bullet | 2678 | @itemize @bullet |
2644 | 2679 | ||
2645 | @item | 2680 | @item wlan network card with monitor support and packet injection |
2646 | wlan network card with monitor support and packet injection | ||
2647 | (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) | 2681 | (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) |
2648 | 2682 | ||
2649 | @item | 2683 | @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with |
2650 | Linux kernel with mac80211 stack, introduced in 2.6.22, tested with 2.6.35 | 2684 | 2.6.35 and 2.6.38 |
2651 | and 2.6.38 | ||
2652 | 2685 | ||
2653 | @item | 2686 | @item Wlantools to create the a monitor interface, tested with airmon-ng |
2654 | Wlantools to create the a monitor interface, tested with airmon-ng of the | 2687 | of the aircrack-ng package |
2655 | aircrack-ng package | ||
2656 | @end itemize | 2688 | @end itemize |
2657 | 2689 | ||
2658 | @node Configuration | 2690 | @node Configuration |
2659 | @subsubsection Configuration | 2691 | @subsubsection Configuration |
2660 | 2692 | ||
2661 | There are the following options for the wlan plugin (they should be like this | 2693 | There are the following options for the wlan plugin (they should be like |
2662 | in your default config file, you only need to adjust them if the values are | 2694 | this in your default config file, you only need to adjust them if the |
2663 | incorrect for your system)@ | 2695 | values are incorrect for your system) |
2664 | @code{@ | 2696 | |
2697 | @example | ||
2665 | # section for the wlan transport plugin@ | 2698 | # section for the wlan transport plugin@ |
2666 | [transport-wlan]@ | 2699 | [transport-wlan]@ |
2667 | # interface to use, more information in the | 2700 | # interface to use, more information in the |
@@ -2671,78 +2704,78 @@ INTERFACE = mon0@ | |||
2671 | # 0 use wlan interface,@ | 2704 | # 0 use wlan interface,@ |
2672 | #1 or 2 use loopback driver for tests 1 = server, 2 = client@ | 2705 | #1 or 2 use loopback driver for tests 1 = server, 2 = client@ |
2673 | TESTMODE = 0@ | 2706 | TESTMODE = 0@ |
2674 | } | 2707 | @end example |
2675 | 2708 | ||
2676 | @node Before starting GNUnet | 2709 | @node Before starting GNUnet |
2677 | @subsubsection Before starting GNUnet | 2710 | @subsubsection Before starting GNUnet |
2678 | 2711 | ||
2679 | Before starting GNUnet, you have to make sure that your wlan interface is in | 2712 | Before starting GNUnet, you have to make sure that your wlan interface is |
2680 | monitor mode. One way to put the wlan interface into monitor mode (if your | 2713 | in monitor mode. One way to put the wlan interface into monitor mode (if |
2681 | interface name is wlan0) is by executing:@ | 2714 | your interface name is wlan0) is by executing: |
2682 | @code{@ | 2715 | |
2716 | @example | ||
2683 | sudo airmon-ng start wlan0@ | 2717 | sudo airmon-ng start wlan0@ |
2684 | } | 2718 | @end example |
2685 | 2719 | ||
2686 | Here is an example what the result should look like:@ | 2720 | @noindent |
2687 | @code{@ | 2721 | Here is an example what the result should look like: |
2722 | |||
2723 | @example | ||
2688 | Interface Chipset Driver@ | 2724 | Interface Chipset Driver@ |
2689 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]@ | 2725 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]@ |
2690 | (monitor mode enabled on mon0)@ | 2726 | (monitor mode enabled on mon0)@ |
2691 | }@ | 2727 | @end example |
2728 | |||
2729 | @noindent | ||
2692 | The monitor interface is mon0 is the one that you have to put into the | 2730 | The monitor interface is mon0 is the one that you have to put into the |
2693 | configuration file. | 2731 | configuration file. |
2694 | 2732 | ||
2695 | @node Limitations and known bugs | 2733 | @node Limitations and known bugs |
2696 | @subsubsection Limitations and known bugs | 2734 | @subsubsection Limitations and known bugs |
2697 | 2735 | ||
2698 | Wlan speed is at the maximum of 1 Mbit/s because support for choosing the wlan | 2736 | Wlan speed is at the maximum of 1 Mbit/s because support for choosing the |
2699 | speed with packet injection was removed in newer kernels. Please pester the | 2737 | wlan speed with packet injection was removed in newer kernels. |
2700 | kernel developers about fixing this. | 2738 | Please pester the kernel developers about fixing this. |
2701 | 2739 | ||
2702 | The interface channel depends on the wlan network that the card is connected | 2740 | The interface channel depends on the wlan network that the card is |
2703 | to. If no connection has been made since the start of the computer, it is | 2741 | connected to. If no connection has been made since the start of the |
2704 | usually the first channel of the card. Peers will only find each other and | 2742 | computer, it is usually the first channel of the card. |
2705 | communicate if they are on the same channel. Channels must be set manually | 2743 | Peers will only find each other and communicate if they are on the same |
2706 | (i.e. using @code{iwconfig wlan0 channel 1}). | 2744 | channel. Channels must be set manually (i.e. using |
2745 | @code{iwconfig wlan0 channel 1}). | ||
2707 | 2746 | ||
2708 | 2747 | ||
2709 | @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx | 2748 | @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx |
2710 | @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx | 2749 | @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx |
2711 | 2750 | ||
2712 | The HTTP plugin supports data transfer using reverse proxies. A reverse proxy | 2751 | The HTTP plugin supports data transfer using reverse proxies. A reverse |
2713 | forwards the HTTP request he receives with a certain URL to another webserver, | 2752 | proxy forwards the HTTP request he receives with a certain URL to another |
2714 | here a GNUnet peer. | 2753 | webserver, here a GNUnet peer. |
2715 | 2754 | ||
2716 | So if you have a running Apache or nginx webserver you can configure it to be a | 2755 | So if you have a running Apache or nginx webserver you can configure it to |
2717 | GNUnet reverse proxy. Especially if you have a well-known webiste this improves | 2756 | be a GNUnet reverse proxy. Especially if you have a well-known webiste |
2718 | censorship resistance since it looks as normal surfing behaviour. | 2757 | this improves censorship resistance since it looks as normal surfing |
2758 | behaviour. | ||
2719 | 2759 | ||
2720 | To do so, you have to do two things: | 2760 | To do so, you have to do two things: |
2721 | 2761 | ||
2722 | @itemize @bullet | 2762 | @itemize @bullet |
2723 | 2763 | @item Configure your webserver to forward the GNUnet HTTP traffic | |
2724 | @item | 2764 | @item Configure your GNUnet peer to announce the respective address |
2725 | Configure your webserver to forward the GNUnet HTTP traffic | ||
2726 | |||
2727 | @item | ||
2728 | Configure your GNUnet peer to announce the respective address | ||
2729 | @end itemize | 2765 | @end itemize |
2730 | 2766 | ||
2731 | As an example we want to use GNUnet peer running: | 2767 | As an example we want to use GNUnet peer running: |
2732 | 2768 | ||
2733 | @itemize @bullet | 2769 | @itemize @bullet |
2734 | 2770 | ||
2735 | @item | 2771 | @item HTTP server plugin on @code{gnunet.foo.org:1080} |
2736 | HTTP server plugin on @code{gnunet.foo.org:1080} | ||
2737 | 2772 | ||
2738 | @item | 2773 | @item HTTPS server plugin on @code{gnunet.foo.org:4433} |
2739 | HTTPS server plugin on @code{gnunet.foo.org:4433} | ||
2740 | 2774 | ||
2741 | @item | 2775 | @item A apache or nginx webserver on |
2742 | A apache or nginx webserver on @uref{http://www.foo.org/, http://www.foo.org:80/} | 2776 | @uref{http://www.foo.org/, http://www.foo.org:80/} |
2743 | 2777 | ||
2744 | @item | 2778 | @item A apache or nginx webserver on https://www.foo.org:443/ |
2745 | A apache or nginx webserver on https://www.foo.org:443/ | ||
2746 | @end itemize | 2779 | @end itemize |
2747 | 2780 | ||
2748 | And we want the webserver to accept GNUnet traffic under | 2781 | And we want the webserver to accept GNUnet traffic under |
@@ -2752,29 +2785,32 @@ And we want the webserver to accept GNUnet traffic under | |||
2752 | 2785 | ||
2753 | First of all you need mod_proxy installed. | 2786 | First of all you need mod_proxy installed. |
2754 | 2787 | ||
2755 | Edit your webserver configuration. Edit @code{/etc/apache2/apache2.conf} or | 2788 | Edit your webserver configuration. Edit |
2756 | the site-specific configuration file. | 2789 | @code{/etc/apache2/apache2.conf} or the site-specific configuration file. |
2757 | 2790 | ||
2758 | In the respective @code{server config},@code{virtual host} or | 2791 | In the respective @code{server config},@code{virtual host} or |
2759 | @code{directory} section add the following lines:@ | 2792 | @code{directory} section add the following lines: |
2760 | @code{@ | 2793 | |
2794 | @example | ||
2761 | ProxyTimeout 300@ | 2795 | ProxyTimeout 300@ |
2762 | ProxyRequests Off@ | 2796 | ProxyRequests Off@ |
2763 | <Location /bar/ >@ | 2797 | <Location /bar/ >@ |
2764 | ProxyPass http://gnunet.foo.org:1080/@ | 2798 | ProxyPass http://gnunet.foo.org:1080/@ |
2765 | ProxyPassReverse http://gnunet.foo.org:1080/@ | 2799 | ProxyPassReverse http://gnunet.foo.org:1080/@ |
2766 | </Location>@ | 2800 | </Location>@ |
2767 | } | 2801 | @end example |
2768 | 2802 | ||
2803 | @noindent | ||
2769 | @strong{Configure your Apache2 HTTPS webserver} | 2804 | @strong{Configure your Apache2 HTTPS webserver} |
2770 | 2805 | ||
2771 | We assume that you already have an HTTPS server running, if not please check | 2806 | We assume that you already have an HTTPS server running, if not please |
2772 | how to configure a HTTPS host. An easy to use example is the | 2807 | check how to configure a HTTPS host. An easy to use example is the |
2773 | @file{apache2/sites-available/default-ssl} example configuration file. | 2808 | @file{apache2/sites-available/default-ssl} example configuration file. |
2774 | 2809 | ||
2775 | In the respective HTTPS @code{server config},@code{virtual host} or | 2810 | In the respective HTTPS @code{server config},@code{virtual host} or |
2776 | @code{directory} section add the following lines:@ | 2811 | @code{directory} section add the following lines: |
2777 | @code{@ | 2812 | |
2813 | @example | ||
2778 | SSLProxyEngine On@ | 2814 | SSLProxyEngine On@ |
2779 | ProxyTimeout 300@ | 2815 | ProxyTimeout 300@ |
2780 | ProxyRequests Off@ | 2816 | ProxyRequests Off@ |
@@ -2782,10 +2818,11 @@ In the respective HTTPS @code{server config},@code{virtual host} or | |||
2782 | ProxyPass https://gnunet.foo.org:4433/@ | 2818 | ProxyPass https://gnunet.foo.org:4433/@ |
2783 | ProxyPassReverse https://gnunet.foo.org:4433/@ | 2819 | ProxyPassReverse https://gnunet.foo.org:4433/@ |
2784 | </Location>@ | 2820 | </Location>@ |
2785 | } | 2821 | @end example |
2786 | 2822 | ||
2787 | More information about the apache mod_proxy configuration can be found unter:@ | 2823 | @noindent |
2788 | @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass} | 2824 | More information about the apache mod_proxy configuration can be found |
2825 | at @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass} | ||
2789 | 2826 | ||
2790 | @strong{Configure your nginx HTTPS webserver} | 2827 | @strong{Configure your nginx HTTPS webserver} |
2791 | 2828 | ||
@@ -2793,20 +2830,23 @@ Since nginx does not support chunked encoding, you first of all have to | |||
2793 | install @code{chunkin}:@ | 2830 | install @code{chunkin}:@ |
2794 | @uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule} | 2831 | @uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule} |
2795 | 2832 | ||
2796 | To enable chunkin add:@ | 2833 | To enable chunkin add: |
2797 | @code{@ | 2834 | |
2835 | @example | ||
2798 | chunkin on;@ | 2836 | chunkin on;@ |
2799 | error_page 411 = @@my_411_error;@ | 2837 | error_page 411 = @@my_411_error;@ |
2800 | location @@my_411_error @{@ | 2838 | location @@my_411_error @{@ |
2801 | chunkin_resume;@ | 2839 | chunkin_resume;@ |
2802 | @}@ | 2840 | @}@ |
2803 | } | 2841 | @end example |
2804 | 2842 | ||
2805 | Edit your webserver configuration. Edit @code{/etc/nginx/nginx.conf} or the | 2843 | @noindent |
2806 | site-specific configuration file. | 2844 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or |
2845 | the site-specific configuration file. | ||
2807 | 2846 | ||
2808 | In the @code{server} section add:@ | 2847 | In the @code{server} section add:@ |
2809 | @code{@ | 2848 | |
2849 | @example | ||
2810 | location /bar/@ | 2850 | location /bar/@ |
2811 | @{@ | 2851 | @{@ |
2812 | proxy_pass http://gnunet.foo.org:1080/;@ | 2852 | proxy_pass http://gnunet.foo.org:1080/;@ |
@@ -2816,15 +2856,17 @@ In the @code{server} section add:@ | |||
2816 | proxy_http_version 1.1; # 1.0 default@ | 2856 | proxy_http_version 1.1; # 1.0 default@ |
2817 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@ | 2857 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@ |
2818 | @}@ | 2858 | @}@ |
2819 | @code{}} | 2859 | @end example |
2820 | 2860 | ||
2861 | @noindent | ||
2821 | @strong{Configure your nginx HTTPS webserver} | 2862 | @strong{Configure your nginx HTTPS webserver} |
2822 | 2863 | ||
2823 | Edit your webserver configuration. Edit @code{/etc/nginx/nginx.conf} or the | 2864 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or |
2824 | site-specific configuration file. | 2865 | the site-specific configuration file. |
2866 | |||
2867 | In the @code{server} section add: | ||
2825 | 2868 | ||
2826 | In the @code{server} section add:@ | 2869 | @example |
2827 | @code{@ | ||
2828 | ssl_session_timeout 6m;@ | 2870 | ssl_session_timeout 6m;@ |
2829 | location /bar/@ | 2871 | location /bar/@ |
2830 | @{@ | 2872 | @{@ |
@@ -2835,55 +2877,66 @@ In the @code{server} section add:@ | |||
2835 | proxy_http_version 1.1; # 1.0 default@ | 2877 | proxy_http_version 1.1; # 1.0 default@ |
2836 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@ | 2878 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@ |
2837 | @}@ | 2879 | @}@ |
2838 | @code{}} | 2880 | @end example |
2839 | 2881 | ||
2882 | @noindent | ||
2840 | @strong{Configure your GNUnet peer} | 2883 | @strong{Configure your GNUnet peer} |
2841 | 2884 | ||
2842 | To have your GNUnet peer announce the address, you have to specify the | 2885 | To have your GNUnet peer announce the address, you have to specify the |
2886 | @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} | ||
2887 | section: | ||
2843 | 2888 | ||
2844 | @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} section:@ | 2889 | @example |
2845 | @code{@ | ||
2846 | [transport-http_server]@ | 2890 | [transport-http_server]@ |
2847 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/@ | 2891 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/@ |
2848 | }@ | 2892 | @end example |
2849 | and/or@ | 2893 | |
2850 | @code{[transport-https_server]} section:@ | 2894 | @noindent |
2851 | @code{@ | 2895 | and/or @code{[transport-https_server]} section: |
2896 | |||
2897 | @example | ||
2852 | [transport-https_server]@ | 2898 | [transport-https_server]@ |
2853 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/@ | 2899 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/@ |
2854 | } | 2900 | @end example |
2855 | 2901 | ||
2902 | @noindent | ||
2856 | Now restart your webserver and your peer... | 2903 | Now restart your webserver and your peer... |
2857 | 2904 | ||
2858 | @node Blacklisting peers | 2905 | @node Blacklisting peers |
2859 | @subsection Blacklisting peers | 2906 | @subsection Blacklisting peers |
2860 | 2907 | ||
2861 | Transport service supports to deny connecting to a specific peer of to a | 2908 | Transport service supports to deny connecting to a specific peer of to a |
2862 | specific peer with a specific transport plugin using te blacklisting component | 2909 | specific peer with a specific transport plugin using te blacklisting |
2863 | of transport service. With@ blacklisting it is possible to deny connections to | 2910 | component of transport service. With@ blacklisting it is possible to deny |
2864 | specific peers of@ to use a specific plugin to a specific peer. Peers can be | 2911 | connections to specific peers of@ to use a specific plugin to a specific |
2865 | blacklisted using@ the configuration or a blacklist client can be asked. | 2912 | peer. Peers can be blacklisted using@ the configuration or a blacklist |
2913 | client can be asked. | ||
2866 | 2914 | ||
2867 | To blacklist peers using the configuration you have to add a section to your@ | 2915 | To blacklist peers using the configuration you have to add a section to |
2868 | configuration containing the peer id of the peer to blacklist and the plugin@ | 2916 | your@ configuration containing the peer id of the peer to blacklist and |
2869 | if required. | 2917 | the plugin@ if required. |
2870 | 2918 | ||
2871 | Example:@ | 2919 | Example:@ |
2872 | To blacklist connections to P565... on peer AG2P... using tcp add:@ | 2920 | |
2873 | @code{@ | 2921 | To blacklist connections to P565... on peer AG2P... using tcp add:@ |
2922 | |||
2923 | @c FIXME: This is too long and produces errors in the pdf. | ||
2924 | @example | ||
2874 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ | 2925 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ |
2875 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp@ | 2926 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp@ |
2876 | }@ | 2927 | @end example |
2877 | To blacklist connections to P565... on peer AG2P... using all plugins add:@ | 2928 | |
2878 | @code{@ | 2929 | To blacklist connections to P565... on peer AG2P... using all plugins add:@ |
2930 | |||
2931 | @example | ||
2879 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ | 2932 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ |
2880 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@ | 2933 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@ |
2881 | } | 2934 | @end example |
2882 | 2935 | ||
2883 | You can also add a blacklist client usign the blacklist api. On a blacklist@ | 2936 | You can also add a blacklist client usign the blacklist api. On a |
2884 | check, blacklisting first checks internally if the peer is blacklisted and@ | 2937 | blacklist check, blacklisting first checks internally if the peer is |
2885 | if not, it asks the blacklisting clients. Clients are asked if it is OK to@ | 2938 | blacklisted and if not, it asks the blacklisting clients. Clients are |
2886 | connect to a peer ID, the plugin is omitted. | 2939 | asked if it is OK to connect to a peer ID, the plugin is omitted. |
2887 | 2940 | ||
2888 | On blacklist check for (peer, plugin) | 2941 | On blacklist check for (peer, plugin) |
2889 | @itemize @bullet | 2942 | @itemize @bullet |
@@ -2898,12 +2951,13 @@ On blacklist check for (peer, plugin) | |||
2898 | @node Configuration of the HTTP and HTTPS transport plugins | 2951 | @node Configuration of the HTTP and HTTPS transport plugins |
2899 | @subsection Configuration of the HTTP and HTTPS transport plugins | 2952 | @subsection Configuration of the HTTP and HTTPS transport plugins |
2900 | 2953 | ||
2901 | The client part of the http and https transport plugins can be configured to | 2954 | The client part of the http and https transport plugins can be configured |
2902 | use a proxy to connect to the hostlist server. This functionality can be | 2955 | to use a proxy to connect to the hostlist server. This functionality can |
2903 | configured in the configuration file directly or using the gnunet-setup tool. | 2956 | be configured in the configuration file directly or using the |
2957 | gnunet-setup tool. | ||
2904 | 2958 | ||
2905 | The both the HTTP and HTTPS clients support the following proxy types at the | 2959 | The both the HTTP and HTTPS clients support the following proxy types at |
2906 | moment: | 2960 | the moment: |
2907 | 2961 | ||
2908 | @itemize @bullet | 2962 | @itemize @bullet |
2909 | @item HTTP 1.1 proxy | 2963 | @item HTTP 1.1 proxy |
@@ -2913,16 +2967,17 @@ moment: | |||
2913 | In addition authentication at the proxy with username and password can be | 2967 | In addition authentication at the proxy with username and password can be |
2914 | configured. | 2968 | configured. |
2915 | 2969 | ||
2916 | To configure proxy support for the clients in the gnunet-setup tool, select the | 2970 | To configure proxy support for the clients in the gnunet-setup tool, |
2917 | "transport" tab and activate the respective plugin. Now you can select the | 2971 | select the "transport" tab and activate the respective plugin. Now you |
2918 | appropriate proxy type. The hostname or IP address (including port if required) | 2972 | can select the appropriate proxy type. The hostname or IP address |
2919 | has to be entered in the "Proxy hostname" textbox. If required, enter username | 2973 | (including port if required) has to be entered in the "Proxy hostname" |
2920 | and password in the "Proxy username" and "Proxy password" boxes. Be aware that | 2974 | textbox. If required, enter username and password in the "Proxy username" |
2921 | these information will be stored in the configuration in plain text. | 2975 | and "Proxy password" boxes. Be aware that these information will be stored |
2976 | in the configuration in plain text. | ||
2922 | 2977 | ||
2923 | To configure these options directly in the configuration, you can configure the | 2978 | To configure these options directly in the configuration, you can |
2924 | following settings in the [transport-http_client] and [transport-https_client] | 2979 | configure the following settings in the [transport-http_client] and |
2925 | section of the configuration: | 2980 | [transport-https_client] section of the configuration: |
2926 | 2981 | ||
2927 | @example | 2982 | @example |
2928 | # Type of proxy server,@ | 2983 | # Type of proxy server,@ |
@@ -2955,114 +3010,122 @@ section of the configuration: | |||
2955 | @node Configuring system-wide DNS interception | 3010 | @node Configuring system-wide DNS interception |
2956 | @subsubsection Configuring system-wide DNS interception | 3011 | @subsubsection Configuring system-wide DNS interception |
2957 | 3012 | ||
2958 | Before you install GNUnet, make sure you have a user and group 'gnunet' as well | 3013 | Before you install GNUnet, make sure you have a user and group 'gnunet' |
2959 | as an empty group 'gnunetdns'. | 3014 | as well as an empty group 'gnunetdns'. |
2960 | 3015 | ||
2961 | When using GNUnet with system-wide DNS interception, it is absolutely necessary | 3016 | When using GNUnet with system-wide DNS interception, it is absolutely |
2962 | for all GNUnet service processes to be started by @code{gnunet-service-arm} as | 3017 | necessary for all GNUnet service processes to be started by |
2963 | user and group 'gnunet'. You also need to be sure to run @code{make install} as | 3018 | @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be |
2964 | root (or use the @code{sudo} option to configure) to grant GNUnet sufficient | 3019 | sure to run @code{make install} as root (or use the @code{sudo} option to |
2965 | privileges. | 3020 | configure) to grant GNUnet sufficient privileges. |
2966 | 3021 | ||
2967 | With this setup, all that is required for enabling system-wide DNS interception | 3022 | With this setup, all that is required for enabling system-wide DNS |
2968 | is for some GNUnet component (VPN or GNS) to request it. The | 3023 | interception is for some GNUnet component (VPN or GNS) to request it. |
2969 | @code{gnunet-service-dns} will then start helper programs that will make the | 3024 | The @code{gnunet-service-dns} will then start helper programs that will |
2970 | necessary changes to your firewall (@code{iptables}) rules. | 3025 | make the necessary changes to your firewall (@code{iptables}) rules. |
2971 | 3026 | ||
2972 | Note that this will NOT work if your system sends out DNS traffic to a | 3027 | Note that this will NOT work if your system sends out DNS traffic to a |
2973 | link-local IPv6 address, as in this case GNUnet can intercept the traffic, but | 3028 | link-local IPv6 address, as in this case GNUnet can intercept the traffic, |
2974 | not inject the responses from the link-local IPv6 address. Hence you cannot use | 3029 | but not inject the responses from the link-local IPv6 address. Hence you |
2975 | system-wide DNS interception in conjunction with link-local IPv6-based DNS | 3030 | cannot use system-wide DNS interception in conjunction with link-local |
2976 | servers. If such a DNS server is used, it will bypass GNUnet's DNS traffic | 3031 | IPv6-based DNS servers. If such a DNS server is used, it will bypass |
2977 | interception. | 3032 | GNUnet's DNS traffic interception. |
2978 | 3033 | ||
3034 | Using the GNU Name System (GNS) requires two different configuration | ||
3035 | steps. | ||
3036 | First of all, GNS needs to be integrated with the operating system. Most | ||
3037 | of this section is about the operating system level integration. | ||
2979 | 3038 | ||
3039 | Additionally, each individual user who wants to use the system must also | ||
3040 | initialize his GNS zones. This can be done by running (after starting | ||
3041 | GNUnet) | ||
2980 | 3042 | ||
2981 | Using the GNU Name System (GNS) requires two different configuration steps. | 3043 | @example |
2982 | First of all, GNS needs to be integrated with the operating system. Most of | 3044 | $ gnunet-gns-import.sh |
2983 | this section is about the operating system level integration. | 3045 | @end example |
2984 | 3046 | ||
2985 | Additionally, each individual user who wants to use the system must also | 3047 | @noindent |
2986 | initialize his GNS zones. This can be done by running (after starting GNUnet)@ | ||
2987 | @code{@ | ||
2988 | $ gnunet-gns-import.sh@ | ||
2989 | }@ | ||
2990 | after the local GNUnet peer has been started. Note that the namestore (in | 3048 | after the local GNUnet peer has been started. Note that the namestore (in |
2991 | particular the namestore database backend) should not be reconfigured | 3049 | particular the namestore database backend) should not be reconfigured |
2992 | afterwards (as records are not automatically migrated between backends). | 3050 | afterwards (as records are not automatically migrated between backends). |
2993 | 3051 | ||
2994 | The remainder of this chapter will detail the various methods for configuring | 3052 | The remainder of this chapter will detail the various methods for |
2995 | the use of GNS with your operating system. | 3053 | configuring the use of GNS with your operating system. |
2996 | 3054 | ||
2997 | At this point in time you have different options depending on your OS: | 3055 | At this point in time you have different options depending on your OS: |
3056 | |||
2998 | @table @asis | 3057 | @table @asis |
2999 | 3058 | ||
3000 | @item Use the gnunet-gns-proxy This approach works for all operating systems | 3059 | @item Use the gnunet-gns-proxy This approach works for all operating |
3001 | and is likely the easiest. However, it enables GNS only for browsers, not for | 3060 | systems and is likely the easiest. However, it enables GNS only for |
3002 | other applications that might be using DNS, such as SSH. Still, using the proxy | 3061 | browsers, not for other applications that might be using DNS, such as SSH. |
3003 | is required for using HTTP with GNS and is thus recommended for all users. To | 3062 | Still, using the proxy is required for using HTTP with GNS and is thus |
3004 | do this, you simply have to run the @code{gnunet-gns-proxy-setup-ca} script as | 3063 | recommended for all users. To do this, you simply have to run the |
3005 | the user who will run the browser (this will create a GNS certificate authority | 3064 | @code{gnunet-gns-proxy-setup-ca} script as the user who will run the |
3006 | (CA) on your system and import its key into your browser), then start | 3065 | browser (this will create a GNS certificate authority (CA) on your system |
3007 | @code{gnunet-gns-proxy} and inform your browser to use the Socks5 proxy which | 3066 | and import its key into your browser), then start @code{gnunet-gns-proxy} |
3067 | and inform your browser to use the Socks5 proxy which | ||
3008 | @code{gnunet-gns-proxy} makes available by default on port 7777. | 3068 | @code{gnunet-gns-proxy} makes available by default on port 7777. |
3009 | @item Use a | 3069 | @item Use a nsswitch plugin (recommended on GNU systems) |
3010 | nsswitch plugin (recommended on GNU systems) This approach has the advantage of | 3070 | This approach has the advantage of offering fully personalized resolution |
3011 | offering fully personalized resolution even on multi-user systems. A potential | 3071 | even on multi-user systems. A potential disadvantage is that some |
3012 | disadvantage is that some applications might be able to bypass GNS. | 3072 | applications might be able to bypass GNS. |
3013 | @item Use | 3073 | @item Use a W32 resolver plugin (recommended on W32) |
3014 | a W32 resolver plugin (recommended on W32) This is currently the only option on | 3074 | This is currently the only option on W32 systems. |
3015 | W32 systems. | 3075 | @item Use system-wide DNS packet interception |
3016 | @item Use system-wide DNS packet interception This approach is | 3076 | This approach is recommended for the GNUnet VPN. It can be used to handle |
3017 | recommended for the GNUnet VPN. It can be used to handle GNS at the same time; | 3077 | GNS at the same time; however, if you only use this method, you will only |
3018 | however, if you only use this method, you will only get one root zone per | 3078 | get one root zone per machine (not so great for multi-user systems). |
3019 | machine (not so great for multi-user systems). | ||
3020 | @end table | 3079 | @end table |
3021 | 3080 | ||
3022 | 3081 | You can combine system-wide DNS packet interception with the nsswitch | |
3023 | You can combine system-wide DNS packet interception with the nsswitch plugin.@ | 3082 | plugin. |
3024 | The setup of the system-wide DNS interception is described here. All of the | 3083 | The setup of the system-wide DNS interception is described here. All of |
3025 | other GNS-specific configuration steps are described in the following sections. | 3084 | the other GNS-specific configuration steps are described in the following |
3085 | sections. | ||
3026 | 3086 | ||
3027 | @node Configuring the GNS nsswitch plugin | 3087 | @node Configuring the GNS nsswitch plugin |
3028 | @subsubsection Configuring the GNS nsswitch plugin | 3088 | @subsubsection Configuring the GNS nsswitch plugin |
3029 | 3089 | ||
3030 | The Name Service Switch (NSS) is a facility in Unix-like operating systems that | 3090 | The Name Service Switch (NSS) is a facility in Unix-like operating systems |
3031 | provides a variety of sources for common configuration databases and name | 3091 | that provides a variety of sources for common configuration databases and |
3032 | resolution mechanisms. A system administrator usually configures the operating | 3092 | name resolution mechanisms. |
3033 | system's name services using the file /etc/nsswitch.conf. | 3093 | A system administrator usually configures the operating system's name |
3094 | services using the file @file{/etc/nsswitch.conf}. | ||
3034 | 3095 | ||
3035 | GNS provides a NSS plugin to integrate GNS name resolution with the operating | 3096 | GNS provides a NSS plugin to integrate GNS name resolution with the |
3036 | system's name resolution process. To use the GNS NSS plugin you have to either | 3097 | operating system's name resolution process. |
3098 | To use the GNS NSS plugin you have to either | ||
3037 | 3099 | ||
3038 | @itemize @bullet | 3100 | @itemize @bullet |
3039 | 3101 | @item install GNUnet as root or | |
3040 | @item | 3102 | @item compile GNUnet with the @code{--with-sudo=yes} switch. |
3041 | install GNUnet as root or | ||
3042 | |||
3043 | @item | ||
3044 | compile GNUnet with the @code{--with-sudo=yes} switch. | ||
3045 | @end itemize | 3103 | @end itemize |
3046 | 3104 | ||
3047 | Name resolution is controlled by the @emph{hosts} section in the NSS | 3105 | Name resolution is controlled by the @emph{hosts} section in the NSS |
3048 | configuration. By default this section first performs a lookup in the | 3106 | configuration. By default this section first performs a lookup in the |
3049 | /etc/hosts file and then in DNS. The nsswitch file should contain a line | 3107 | /etc/hosts file and then in DNS. The nsswitch file should contain a line |
3050 | similar to:@ | 3108 | similar to: |
3051 | @code{@ | ||
3052 | hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4@ | ||
3053 | } | ||
3054 | 3109 | ||
3055 | Here the GNS NSS plugin can be added to perform a GNS lookup before performing | 3110 | @example |
3056 | a DNS lookup. The GNS NSS plugin has to be added to the "hosts" section in | 3111 | hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 |
3057 | /etc/nsswitch.conf file before DNS related plugins:@ | 3112 | @end example |
3058 | @code{@ | ||
3059 | ...@ | ||
3060 | hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4@ | ||
3061 | ...@ | ||
3062 | } | ||
3063 | 3113 | ||
3064 | The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not found | 3114 | @noindent |
3065 | in GNS it will not be queried in DNS. | 3115 | Here the GNS NSS plugin can be added to perform a GNS lookup before |
3116 | performing a DNS lookup. | ||
3117 | The GNS NSS plugin has to be added to the "hosts" section in | ||
3118 | @file{/etc/nsswitch.conf} file before DNS related plugins: | ||
3119 | |||
3120 | @example | ||
3121 | ... | ||
3122 | hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 | ||
3123 | ... | ||
3124 | @end example | ||
3125 | |||
3126 | @noindent | ||
3127 | The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not | ||
3128 | found in GNS it will not be queried in DNS. | ||
3066 | 3129 | ||
3067 | @node Configuring GNS on W32 | 3130 | @node Configuring GNS on W32 |
3068 | @subsubsection Configuring GNS on W32 | 3131 | @subsubsection Configuring GNS on W32 |
@@ -3071,140 +3134,147 @@ This document is a guide to configuring GNU Name System on W32-compatible | |||
3071 | platforms. | 3134 | platforms. |
3072 | 3135 | ||
3073 | After GNUnet is installed, run the w32nsp-install tool: | 3136 | After GNUnet is installed, run the w32nsp-install tool: |
3137 | |||
3074 | @example | 3138 | @example |
3075 | w32nsp-install.exe libw32nsp-0.dll | 3139 | w32nsp-install.exe libw32nsp-0.dll |
3076 | @end example | 3140 | @end example |
3077 | 3141 | ||
3078 | 3142 | @noindent | |
3079 | ('0' is the library version of W32 NSP; it might increase in the future, | 3143 | ('0' is the library version of W32 NSP; it might increase in the future, |
3080 | change the invocation accordingly). | 3144 | change the invocation accordingly). |
3081 | 3145 | ||
3082 | This will install GNS namespace provider into the system and allow other | 3146 | This will install GNS namespace provider into the system and allow other |
3083 | applications to resolve names that end in '@strong{gnu}' and '@strong{zkey}'. | 3147 | applications to resolve names that end in '@strong{gnu}' |
3084 | Note that namespace provider requires gnunet-gns-helper-service-w32 to be | 3148 | and '@strong{zkey}'. Note that namespace provider requires |
3085 | running, as well as gns service itself (and its usual dependencies). | 3149 | gnunet-gns-helper-service-w32 to be running, as well as gns service |
3150 | itself (and its usual dependencies). | ||
3086 | 3151 | ||
3087 | Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, and this | 3152 | Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, |
3088 | is where gnunet-gns-helper-service-w32 should be listening to (and is | 3153 | and this is where gnunet-gns-helper-service-w32 should be listening to |
3089 | configured to listen to by default). | 3154 | (and is configured to listen to by default). |
3090 | 3155 | ||
3091 | To uninstall the provider, run: | 3156 | To uninstall the provider, run: |
3157 | |||
3092 | @example | 3158 | @example |
3093 | w32nsp-uninstall.exe | 3159 | w32nsp-uninstall.exe |
3094 | @end example | 3160 | @end example |
3095 | 3161 | ||
3096 | 3162 | @noindent | |
3097 | (uses provider GUID to uninstall it, does not need a dll name). | 3163 | (uses provider GUID to uninstall it, does not need a dll name). |
3098 | 3164 | ||
3099 | Note that while MSDN claims that other applications will only be able to use | 3165 | Note that while MSDN claims that other applications will only be able to |
3100 | the new namespace provider after re-starting, in reality they might stat to use | 3166 | use the new namespace provider after re-starting, in reality they might |
3101 | it without that. Conversely, they might stop using the provider after it's been | 3167 | stat to use it without that. Conversely, they might stop using the |
3102 | uninstalled, even if they were not re-started. W32 will not permit namespace | 3168 | provider after it's been uninstalled, even if they were not re-started. |
3103 | provider library to be deleted or overwritten while the provider is installed, | 3169 | W32 will not permit namespace provider library to be deleted or |
3104 | and while there is at least one process still using it (even after it was | 3170 | overwritten while the provider is installed, and while there is at least |
3105 | uninstalled). | 3171 | one process still using it (even after it was uninstalled). |
3106 | 3172 | ||
3107 | @node GNS Proxy Setup | 3173 | @node GNS Proxy Setup |
3108 | @subsubsection GNS Proxy Setup | 3174 | @subsubsection GNS Proxy Setup |
3109 | 3175 | ||
3110 | When using the GNU Name System (GNS) to browse the WWW, there are several | 3176 | When using the GNU Name System (GNS) to browse the WWW, there are several |
3111 | issues that can be solved by adding the GNS Proxy to your setup: | 3177 | issues that can be solved by adding the GNS Proxy to your setup: |
3112 | @itemize @bullet | ||
3113 | 3178 | ||
3179 | @itemize @bullet | ||
3114 | 3180 | ||
3115 | @item If the target website does not support GNS, it might assume that it is | 3181 | @item If the target website does not support GNS, it might assume that it |
3116 | operating under some name in the legacy DNS system (such as example.com). It | 3182 | is operating under some name in the legacy DNS system (such as |
3117 | may then attempt to set cookies for that domain, and the web server might | 3183 | example.com). It may then attempt to set cookies for that domain, and the |
3118 | expect a @code{Host: example.com} header in the request from your browser. | 3184 | web server might expect a @code{Host: example.com} header in the request |
3119 | However, your browser might be using @code{example.gnu} for the @code{Host} | 3185 | from your browser. |
3120 | header and might only accept (and send) cookies for @code{example.gnu}. The GNS | 3186 | However, your browser might be using @code{example.gnu} for the |
3121 | Proxy will perform the necessary translations of the hostnames for cookies and | 3187 | @code{Host} header and might only accept (and send) cookies for |
3122 | HTTP headers (using the LEHO record for the target domain as the desired | 3188 | @code{example.gnu}. The GNS Proxy will perform the necessary translations |
3123 | substitute). | 3189 | of the hostnames for cookies and HTTP headers (using the LEHO record for |
3124 | 3190 | the target domain as the desired substitute). | |
3125 | @item If using HTTPS, the target site might include an SSL certificate which is | 3191 | |
3126 | either only valid for the LEHO domain or might match a TLSA record in GNS. | 3192 | @item If using HTTPS, the target site might include an SSL certificate |
3127 | However, your browser would expect a valid certificate for @code{example.gnu}, | 3193 | which is either only valid for the LEHO domain or might match a TLSA |
3128 | not for some legacy domain name. The proxy will validate the certificate | 3194 | record in GNS. However, your browser would expect a valid certificate for |
3129 | (either against LEHO or TLSA) and then on-the-fly produce a valid certificate | 3195 | @code{example.gnu}, not for some legacy domain name. The proxy will |
3130 | for the exchange, signed by your own CA. Assuming you installed the CA of your | 3196 | validate the certificate (either against LEHO or TLSA) and then |
3131 | proxy in your browser's certificate authority list, your browser will then | 3197 | on-the-fly produce a valid certificate for the exchange, signed by your |
3132 | trust the HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the | 3198 | own CA. Assuming you installed the CA of your proxy in your browser's |
3133 | proxy. | 3199 | certificate authority list, your browser will then trust the |
3200 | HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. | ||
3134 | 3201 | ||
3135 | @item Finally, the proxy will in the future indicate to the server that it | 3202 | @item Finally, the proxy will in the future indicate to the server that it |
3136 | speaks GNS, which will enable server operators to deliver GNS-enabled web sites | 3203 | speaks GNS, which will enable server operators to deliver GNS-enabled web |
3137 | to your browser (and continue to deliver legacy links to legacy browsers) | 3204 | sites to your browser (and continue to deliver legacy links to legacy |
3205 | browsers) | ||
3138 | @end itemize | 3206 | @end itemize |
3139 | 3207 | ||
3140 | @node Setup of the GNS CA | 3208 | @node Setup of the GNS CA |
3141 | @subsubsection Setup of the GNS CA | 3209 | @subsubsection Setup of the GNS CA |
3142 | 3210 | ||
3143 | First you need to create a CA certificate that the proxy can use. To do so use | 3211 | First you need to create a CA certificate that the proxy can use. |
3144 | the provided script gnunet-gns-proxy-ca:@ | 3212 | To do so use the provided script gnunet-gns-proxy-ca: |
3145 | @code{@ | ||
3146 | $ gnunet-gns-proxy-setup-ca@ | ||
3147 | } | ||
3148 | 3213 | ||
3214 | @example | ||
3215 | $ gnunet-gns-proxy-setup-ca | ||
3216 | @end example | ||
3217 | |||
3218 | @noindent | ||
3149 | This will create a personal certification authority for you and add this | 3219 | This will create a personal certification authority for you and add this |
3150 | authority to the firefox and chrome database. The proxy will use the this CA | 3220 | authority to the firefox and chrome database. The proxy will use the this |
3151 | certificate to generate @code{*.gnu} client certificates on the fly. | 3221 | CA certificate to generate @code{*.gnu} client certificates on the fly. |
3152 | 3222 | ||
3153 | Note that the proxy uses libcurl. Make sure your version of libcurl uses GnuTLS | 3223 | Note that the proxy uses libcurl. Make sure your version of libcurl uses |
3154 | and NOT OpenSSL. The proxy will not work with libcurl compiled against | 3224 | GnuTLS and NOT OpenSSL. The proxy will not work with libcurl compiled |
3155 | OpenSSL. | 3225 | against OpenSSL. |
3156 | 3226 | ||
3157 | @node Testing the GNS setup | 3227 | @node Testing the GNS setup |
3158 | @subsubsection Testing the GNS setup | 3228 | @subsubsection Testing the GNS setup |
3159 | 3229 | ||
3160 | Now for testing purposes we can create some records in our zone to test the SSL | 3230 | Now for testing purposes we can create some records in our zone to test |
3161 | functionality of the proxy:@ | 3231 | the SSL functionality of the proxy: |
3162 | @code{@ | ||
3163 | $ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67@ | ||
3164 | $ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org"@ | ||
3165 | } | ||
3166 | 3232 | ||
3167 | At this point we can start the proxy. Simply execute@ | 3233 | @example |
3168 | @code{@ | 3234 | $ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67 |
3169 | $ gnunet-gns-proxy@ | 3235 | $ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org" |
3170 | } | 3236 | @end example |
3237 | |||
3238 | @noindent | ||
3239 | At this point we can start the proxy. Simply execute | ||
3240 | |||
3241 | @example | ||
3242 | $ gnunet-gns-proxy | ||
3243 | @end example | ||
3171 | 3244 | ||
3172 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit this | 3245 | @noindent |
3173 | link.@ If you use firefox you also have to go to about:config and set the key | 3246 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit |
3247 | this link. | ||
3248 | If you use firefox you also have to go to about:config and set the key | ||
3174 | @code{network.proxy.socks_remote_dns} to @code{true}. | 3249 | @code{network.proxy.socks_remote_dns} to @code{true}. |
3175 | 3250 | ||
3176 | When you visit @code{https://homepage.gnu/}, you should get to the | 3251 | When you visit @code{https://homepage.gnu/}, you should get to the |
3177 | @code{https://gnunet.org/} frontpage and the browser (with the correctly | 3252 | @code{https://gnunet.org/} frontpage and the browser (with the correctly |
3178 | configured proxy) should give you a valid SSL certificate for | 3253 | configured proxy) should give you a valid SSL certificate for |
3179 | @code{homepage.gnu} and no warnings. It should look like this@ | 3254 | @code{homepage.gnu} and no warnings. It should look like this: |
3180 | |||
3181 | 3255 | ||
3182 | 3256 | @c insert image here gnunethpgns.png | |
3183 | @table @asis | ||
3184 | @item Attachment | ||
3185 | Size | ||
3186 | @item gnunethpgns.png | ||
3187 | 64.19 KB | ||
3188 | @end table | ||
3189 | 3257 | ||
3190 | @node Automatic Shortening in the GNU Name System | 3258 | @node Automatic Shortening in the GNU Name System |
3191 | @subsubsection Automatic Shortening in the GNU Name System | 3259 | @subsubsection Automatic Shortening in the GNU Name System |
3192 | 3260 | ||
3193 | This page describes a possible option for 'automatic name shortening', which | 3261 | This page describes a possible option for 'automatic name shortening', |
3194 | you can choose to enable with the GNU Name System. | 3262 | which you can choose to enable with the GNU Name System. |
3195 | 3263 | ||
3196 | When GNS encounters a name for the first time, it can use the 'NICK' record of | 3264 | When GNS encounters a name for the first time, it can use the 'NICK' |
3197 | the originating zone to automatically generate a name for the zone. If | 3265 | record of the originating zone to automatically generate a name for the |
3198 | automatic shortening is enabled, those auto-generated names will be placed (as | 3266 | zone. If automatic shortening is enabled, those auto-generated names will |
3199 | private records) into your personal 'shorten' zone (to prevent confusion with | 3267 | be placed (as private records) into your personal 'shorten' zone (to |
3200 | manually selected names). Then, in the future, if the same name is encountered | 3268 | prevent confusion with manually selected names). |
3201 | again, GNS will display the shortened name instead (the first time, the long | 3269 | Then, in the future, if the same name is encountered again, GNS will |
3202 | name will still be used as shortening typically happens asynchronously as | 3270 | display the shortened name instead (the first time, the long name will |
3203 | looking up the 'NICK' record takes some time). Using this feature can be a | 3271 | still be used as shortening typically happens asynchronously as looking up |
3204 | convenient way to avoid very long @code{.gnu} names; however, note that names | 3272 | the 'NICK' record takes some time). Using this feature can be a convenient |
3205 | from the shorten-zone are assigned on a first-come-first-serve basis and should | 3273 | way to avoid very long @code{.gnu} names; however, note that names from |
3206 | not be trusted. Furthermore, if you enable this feature, you will no longer see | 3274 | the shorten-zone are assigned on a first-come-first-serve basis and should |
3207 | the full delegation chain for zones once shortening has been applied. | 3275 | not be trusted. Furthermore, if you enable this feature, you will no |
3276 | longer see the full delegation chain for zones once shortening has been | ||
3277 | applied. | ||
3208 | 3278 | ||
3209 | @node Configuring the GNUnet VPN | 3279 | @node Configuring the GNUnet VPN |
3210 | @subsection Configuring the GNUnet VPN | 3280 | @subsection Configuring the GNUnet VPN |
@@ -3220,15 +3290,16 @@ the full delegation chain for zones once shortening has been applied. | |||
3220 | @end menu | 3290 | @end menu |
3221 | 3291 | ||
3222 | Before configuring the GNUnet VPN, please make sure that system-wide DNS | 3292 | Before configuring the GNUnet VPN, please make sure that system-wide DNS |
3223 | interception is configured properly as described in the section on the GNUnet | 3293 | interception is configured properly as described in the section on the |
3224 | DNS setup. | 3294 | GNUnet DNS setup. |
3225 | 3295 | ||
3226 | The default-options for the GNUnet VPN are usually sufficient to use GNUnet as | 3296 | The default-options for the GNUnet VPN are usually sufficient to use |
3227 | a Layer 2 for your Internet connection. However, what you always have to | 3297 | GNUnet as a Layer 2 for your Internet connection. However, what you always |
3228 | specify is which IP protocol you want to tunnel: IPv4, IPv6 or both. | 3298 | have to specify is which IP protocol you want to tunnel: IPv4, IPv6 or |
3229 | Furthermore, if you tunnel both, you most likely should also tunnel all of your | 3299 | both. Furthermore, if you tunnel both, you most likely should also tunnel |
3230 | DNS requests. You theoretically can tunnel "only" your DNS traffic, but that | 3300 | all of your DNS requests. |
3231 | usually makes little sense. | 3301 | You theoretically can tunnel "only" your DNS traffic, but that usually |
3302 | makes little sense. | ||
3232 | 3303 | ||
3233 | The other options as shown on the gnunet-setup tool are: | 3304 | The other options as shown on the gnunet-setup tool are: |
3234 | 3305 | ||
@@ -3236,21 +3307,25 @@ The other options as shown on the gnunet-setup tool are: | |||
3236 | @subsubsection IPv4 address for interface | 3307 | @subsubsection IPv4 address for interface |
3237 | 3308 | ||
3238 | This is the IPv4 address the VPN interface will get. You should pick an | 3309 | This is the IPv4 address the VPN interface will get. You should pick an |
3239 | 'private' IPv4 network that is not yet in use for you system. For example, if | 3310 | 'private' IPv4 network that is not yet in use for you system. For example, |
3240 | you use 10.0.0.1/255.255.0.0 already, you might use 10.1.0.1/255.255.0.0. If | 3311 | if you use 10.0.0.1/255.255.0.0 already, you might use |
3241 | you use 10.0.0.1/255.0.0.0 already, then you might use 192.168.0.1/255.255.0.0. | 3312 | 10.1.0.1/255.255.0.0. |
3242 | If your system is not in a private IP-network, using any of the above will work | 3313 | If you use 10.0.0.1/255.0.0.0 already, then you might use |
3243 | fine.@ You should try to make the mask of the address big enough (255.255.0.0 | 3314 | 192.168.0.1/255.255.0.0. |
3244 | or, even better, 255.0.0.0) to allow more mappings of remote IP Addresses into | 3315 | If your system is not in a private IP-network, using any of the above will |
3245 | this range. However, even a 255.255.255.0-mask will suffice for most users. | 3316 | work fine. |
3317 | You should try to make the mask of the address big enough (255.255.0.0 | ||
3318 | or, even better, 255.0.0.0) to allow more mappings of remote IP Addresses | ||
3319 | into this range. | ||
3320 | However, even a 255.255.255.0-mask will suffice for most users. | ||
3246 | 3321 | ||
3247 | @node IPv6 address for interface | 3322 | @node IPv6 address for interface |
3248 | @subsubsection IPv6 address for interface | 3323 | @subsubsection IPv6 address for interface |
3249 | 3324 | ||
3250 | The IPv6 address the VPN interface will get. Here you can specify any | 3325 | The IPv6 address the VPN interface will get. Here you can specify any |
3251 | non-link-local address (the address should not begin with "fe80:"). A subnet | 3326 | non-link-local address (the address should not begin with "fe80:"). |
3252 | Unique Local Unicast (fd00::/8-prefix) that you are currently not using would | 3327 | A subnet Unique Local Unicast (fd00::/8-prefix) that you are currently |
3253 | be a good choice. | 3328 | not using would be a good choice. |
3254 | 3329 | ||
3255 | @node Configuring the GNUnet VPN DNS | 3330 | @node Configuring the GNUnet VPN DNS |
3256 | @subsubsection Configuring the GNUnet VPN DNS | 3331 | @subsubsection Configuring the GNUnet VPN DNS |
@@ -3260,59 +3335,64 @@ To resolve names for remote nodes, activate the DNS exit option. | |||
3260 | @node Configuring the GNUnet VPN Exit Service | 3335 | @node Configuring the GNUnet VPN Exit Service |
3261 | @subsubsection Configuring the GNUnet VPN Exit Service | 3336 | @subsubsection Configuring the GNUnet VPN Exit Service |
3262 | 3337 | ||
3263 | If you want to allow other users to share your Internet connection (yes, this | 3338 | If you want to allow other users to share your Internet connection (yes, |
3264 | may be dangerous, just as running a Tor exit node) or want to provide access to | 3339 | this may be dangerous, just as running a Tor exit node) or want to |
3265 | services on your host (this should be less dangerous, as long as those services | 3340 | provide access to services on your host (this should be less dangerous, |
3266 | are secure), you have to enable the GNUnet exit daemon. | 3341 | as long as those services are secure), you have to enable the GNUnet exit |
3267 | 3342 | daemon. | |
3268 | You then get to specify which exit functions you want to provide. By enabling | 3343 | |
3269 | the exit daemon, you will always automatically provide exit functions for | 3344 | You then get to specify which exit functions you want to provide. By |
3270 | manually configured local services (this component of the system is under | 3345 | enabling the exit daemon, you will always automatically provide exit |
3271 | development and not documented further at this time). As for those services you | 3346 | functions for manually configured local services (this component of the |
3272 | explicitly specify the target IP address and port, there is no significant | 3347 | system is under |
3273 | security risk in doing so. | 3348 | development and not documented further at this time). As for those |
3274 | 3349 | services you explicitly specify the target IP address and port, there is | |
3275 | Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. Being a | 3350 | no significant security risk in doing so. |
3276 | DNS exit is usually pretty harmless. However, enabling IPv4 or IPv6-exit | 3351 | |
3277 | without further precautions may enable adversaries to access your local | 3352 | Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. |
3278 | network, send spam, attack other systems from your Internet connection and to | 3353 | Being a DNS exit is usually pretty harmless. However, enabling IPv4 or |
3279 | other mischief that will appear to come from your machine. This may or may not | 3354 | IPv6-exit without further precautions may enable adversaries to access |
3280 | get you into legal trouble. If you want to allow IPv4 or IPv6-exit | 3355 | your local network, send spam, attack other systems from your Internet |
3281 | functionality, you should strongly consider adding additional firewall rules | 3356 | connection and to other mischief that will appear to come from your |
3282 | manually to protect your local network and to restrict outgoing TCP traffic | 3357 | machine. This may or may not get you into legal trouble. |
3283 | (i.e. by not allowing access to port 25). While we plan to improve | 3358 | If you want to allow IPv4 or IPv6-exit functionality, you should strongly |
3284 | exit-filtering in the future, you're currently on your own here. Essentially, | 3359 | consider adding additional firewall rules manually to protect your local |
3285 | be prepared for any kind of IP-traffic to exit the respective TUN interface | 3360 | network and to restrict outgoing TCP traffic (i.e. by not allowing access |
3286 | (and GNUnet will enable IP-forwarding and NAT for the interface automatically). | 3361 | to port 25). While we plan to improve exit-filtering in the future, |
3287 | 3362 | you're currently on your own here. | |
3288 | Additional configuration options of the exit as shown by the gnunet-setup tool | 3363 | Essentially, be prepared for any kind of IP-traffic to exit the respective |
3289 | are: | 3364 | TUN interface (and GNUnet will enable IP-forwarding and NAT for the |
3365 | interface automatically). | ||
3366 | |||
3367 | Additional configuration options of the exit as shown by the gnunet-setup | ||
3368 | tool are: | ||
3290 | 3369 | ||
3291 | @node IP Address of external DNS resolver | 3370 | @node IP Address of external DNS resolver |
3292 | @subsubsection IP Address of external DNS resolver | 3371 | @subsubsection IP Address of external DNS resolver |
3293 | 3372 | ||
3294 | If DNS traffic is to exit your machine, it will be send to this DNS resolver. | 3373 | If DNS traffic is to exit your machine, it will be send to this DNS |
3295 | You can specify an IPv4 or IPv6 address. | 3374 | resolver. You can specify an IPv4 or IPv6 address. |
3296 | 3375 | ||
3297 | @node IPv4 address for Exit interface | 3376 | @node IPv4 address for Exit interface |
3298 | @subsubsection IPv4 address for Exit interface | 3377 | @subsubsection IPv4 address for Exit interface |
3299 | 3378 | ||
3300 | This is the IPv4 address the Interface will get. Make the mask of the address | 3379 | This is the IPv4 address the Interface will get. Make the mask of the |
3301 | big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more mappings of | 3380 | address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more |
3302 | IP addresses into this range. As for the VPN interface, any unused, private | 3381 | mappings of IP addresses into this range. As for the VPN interface, any |
3303 | IPv4 address range will do. | 3382 | unused, private IPv4 address range will do. |
3304 | 3383 | ||
3305 | @node IPv6 address for Exit interface | 3384 | @node IPv6 address for Exit interface |
3306 | @subsubsection IPv6 address for Exit interface | 3385 | @subsubsection IPv6 address for Exit interface |
3307 | 3386 | ||
3308 | The public IPv6 address the interface will get. If your kernel is not a very | 3387 | The public IPv6 address the interface will get. If your kernel is not a |
3309 | recent kernel and you are willing to manually enable IPv6-NAT, the IPv6 address | 3388 | very recent kernel and you are willing to manually enable IPv6-NAT, the |
3310 | you specify here must be a globally routed IPv6 address of your host. | 3389 | IPv6 address you specify here must be a globally routed IPv6 address of |
3390 | your host. | ||
3311 | 3391 | ||
3312 | Suppose your host has the address @code{2001:4ca0::1234/64}, then using@ | 3392 | Suppose your host has the address @code{2001:4ca0::1234/64}, then |
3313 | @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, then change at | 3393 | using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, |
3314 | least one bit in the range before the bitmask, in the example above we changed | 3394 | then change at least one bit in the range before the bitmask, in the |
3315 | bit 111 from 0 to 1). | 3395 | example above we changed bit 111 from 0 to 1). |
3316 | 3396 | ||
3317 | You may also have to configure your router to route traffic for the entire | 3397 | You may also have to configure your router to route traffic for the entire |
3318 | subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this | 3398 | subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this |
@@ -3322,107 +3402,114 @@ disabled). | |||
3322 | @node Bandwidth Configuration | 3402 | @node Bandwidth Configuration |
3323 | @subsection Bandwidth Configuration | 3403 | @subsection Bandwidth Configuration |
3324 | 3404 | ||
3325 | You can specify how many bandwidth GNUnet is allowed to use to receive and send | 3405 | You can specify how many bandwidth GNUnet is allowed to use to receive |
3326 | data. This is important for users with limited bandwidth or traffic volume. | 3406 | and send data. This is important for users with limited bandwidth or |
3407 | traffic volume. | ||
3327 | 3408 | ||
3328 | @node Configuring NAT | 3409 | @node Configuring NAT |
3329 | @subsection Configuring NAT | 3410 | @subsection Configuring NAT |
3330 | 3411 | ||
3331 | Most hosts today do not have a normal global IP address but instead are behind | 3412 | Most hosts today do not have a normal global IP address but instead are |
3332 | a router performing Network Address Translation (NAT) which assigns each host | 3413 | behind a router performing Network Address Translation (NAT) which assigns |
3333 | in the local network a private IP address. As a result, these machines cannot | 3414 | each host in the local network a private IP address. |
3334 | trivially receive inbound connections from the Internet. GNUnet supports NAT | 3415 | As a result, these machines cannot trivially receive inbound connections |
3335 | traversal to enable these machines to receive incoming connections from other | 3416 | from the Internet. GNUnet supports NAT traversal to enable these machines |
3336 | peers despite their limitations. | 3417 | to receive incoming connections from other peers despite their |
3337 | 3418 | limitations. | |
3338 | In an ideal world, you can press the "Attempt automatic configuration" button | 3419 | |
3339 | in gnunet-setup to automatically configure your peer correctly. Alternatively, | 3420 | In an ideal world, you can press the "Attempt automatic configuration" |
3340 | your distribution might have already triggered this automatic configuration | 3421 | button in gnunet-setup to automatically configure your peer correctly. |
3341 | during the installation process. However, automatic configuration can fail to | 3422 | Alternatively, your distribution might have already triggered this |
3342 | determine the optimal settings, resulting in your peer either not receiving as | 3423 | automatic configuration during the installation process. |
3343 | many connections as possible, or in the worst case it not connecting to the | 3424 | However, automatic configuration can fail to determine the optimal |
3344 | network at all. | 3425 | settings, resulting in your peer either not receiving as many connections |
3426 | as possible, or in the worst case it not connecting to the network at all. | ||
3345 | 3427 | ||
3346 | To manually configure the peer, you need to know a few things about your | 3428 | To manually configure the peer, you need to know a few things about your |
3347 | network setup. First, determine if you are behind a NAT in the first place. | 3429 | network setup. First, determine if you are behind a NAT in the first |
3348 | This is always the case if your IP address starts with "10.*" or "192.168.*". | 3430 | place. |
3349 | Next, if you have control over your NAT router, you may choose to manually | 3431 | This is always the case if your IP address starts with "10.*" or |
3350 | configure it to allow GNUnet traffic to your host. If you have configured your | 3432 | "192.168.*". Next, if you have control over your NAT router, you may |
3351 | NAT to forward traffic on ports 2086 (and possibly 1080) to your host, you can | 3433 | choose to manually configure it to allow GNUnet traffic to your host. |
3352 | check the "NAT ports have been opened manually" option, which corresponds to | 3434 | If you have configured your NAT to forward traffic on ports 2086 (and |
3353 | the "PUNCHED_NAT" option in the configuration file. If you did not punch your | 3435 | possibly 1080) to your host, you can check the "NAT ports have been opened |
3354 | NAT box, it may still be configured to support UPnP, which allows GNUnet to | 3436 | manually" option, which corresponds to the "PUNCHED_NAT" option in the |
3355 | automatically configure it. In that case, you need to install the "upnpc" | 3437 | configuration file. If you did not punch your NAT box, it may still be |
3356 | command, enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal | 3438 | configured to support UPnP, which allows GNUnet to automatically |
3357 | via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the configuration | 3439 | configure it. In that case, you need to install the "upnpc" command, |
3358 | file). | 3440 | enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal |
3359 | 3441 | via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the | |
3360 | Some NAT boxes can be traversed using the autonomous NAT traversal method. This | 3442 | configuration file). |
3361 | requires certain GNUnet components to be installed with "SUID" prividledges on | 3443 | |
3362 | your system (so if you're installing on a system you do not have administrative | 3444 | Some NAT boxes can be traversed using the autonomous NAT traversal method. |
3363 | rights to, this will not work). If you installed as 'root', you can enable | 3445 | This requires certain GNUnet components to be installed with "SUID" |
3364 | autonomous NAT traversal by checking the "Enable NAT traversal using ICMP | 3446 | prividledges on your system (so if you're installing on a system you do |
3365 | method". The ICMP method requires a way to determine your NAT's external | 3447 | not have administrative rights to, this will not work). |
3366 | (global) IP address. This can be done using either UPnP, DynDNS, or by manual | 3448 | If you installed as 'root', you can enable autonomous NAT traversal by |
3367 | configuration. If you have a DynDNS name or know your external IP address, you | 3449 | checking the "Enable NAT traversal using ICMP method". |
3368 | should enter that name under "External (public) IPv4 address" (which | 3450 | The ICMP method requires a way to determine your NAT's external (global) |
3369 | corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). If you | 3451 | IP address. This can be done using either UPnP, DynDNS, or by manual |
3370 | leave the option empty, GNUnet will try to determine your external IP address | 3452 | configuration. If you have a DynDNS name or know your external IP address, |
3371 | automatically (which may fail, in which case autonomous NAT traversal will then | 3453 | you should enter that name under "External (public) IPv4 address" (which |
3372 | not work). | 3454 | corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). |
3373 | 3455 | If you leave the option empty, GNUnet will try to determine your external | |
3374 | Finally, if you yourself are not behind NAT but want to be able to connect to | 3456 | IP address automatically (which may fail, in which case autonomous |
3375 | NATed peers using autonomous NAT traversal, you need to check the "Enable | 3457 | NAT traversal will then not work). |
3376 | connecting to NATed peers using ICMP method" box. | 3458 | |
3459 | Finally, if you yourself are not behind NAT but want to be able to | ||
3460 | connect to NATed peers using autonomous NAT traversal, you need to check | ||
3461 | the "Enable connecting to NATed peers using ICMP method" box. | ||
3377 | 3462 | ||
3378 | 3463 | ||
3379 | @node Peer configuration for distributions | 3464 | @node Peer configuration for distributions |
3380 | @subsection Peer configuration for distributions | 3465 | @subsection Peer configuration for distributions |
3381 | 3466 | ||
3382 | The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be manually set | 3467 | The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be |
3383 | to "/var/lib/gnunet/data/" as the default "~/.local/share/gnunet/" is probably | 3468 | manually set to "/var/lib/gnunet/data/" as the default |
3384 | not that appropriate in this case. Similarly, distributions may consider | 3469 | "~/.local/share/gnunet/" is probably not that appropriate in this case. |
3385 | pointing "GNUNET_RUNTIME_DIR" to "/var/run/gnunet/" and "GNUNET_HOME" to | 3470 | Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to |
3386 | "/var/lib/gnunet/". Also, should a distribution decide to override system | 3471 | "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a |
3387 | defaults, all of these changes should be done in a custom @file{/etc/gnunet.conf} | 3472 | distribution decide to override system defaults, all of these changes |
3388 | and not in the files in the @file{config.d/} directory. | 3473 | should be done in a custom @file{/etc/gnunet.conf} and not in the files |
3389 | 3474 | in the @file{config.d/} directory. | |
3390 | Given the proposed access permissions, the "gnunet-setup" tool must be run as | 3475 | |
3391 | use "gnunet" (and with option "-c /etc/gnunet.conf" so that it modifies the | 3476 | Given the proposed access permissions, the "gnunet-setup" tool must be |
3392 | system configuration). As always, gnunet-setup should be run after the GNUnet | 3477 | run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it |
3393 | peer was stopped using "gnunet-arm -e". Distributions might want to include a | 3478 | modifies the system configuration). As always, gnunet-setup should be run |
3394 | wrapper for gnunet-setup that allows the desktop-user to "sudo" (i.e. using | 3479 | after the GNUnet peer was stopped using "gnunet-arm -e". Distributions |
3395 | gtksudo) to the "gnunet" user account and then runs "gnunet-arm -e", | 3480 | might want to include a wrapper for gnunet-setup that allows the |
3396 | "gnunet-setup" and "gnunet-arm -s" in sequence. | 3481 | desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account |
3397 | 3482 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | |
3398 | 3483 | sequence. | |
3399 | 3484 | ||
3400 | @node How to start and stop a GNUnet peer | 3485 | @node How to start and stop a GNUnet peer |
3401 | @section How to start and stop a GNUnet peer | 3486 | @section How to start and stop a GNUnet peer |
3402 | 3487 | ||
3403 | This section describes how to start a GNUnet peer. It assumes that you have | 3488 | This section describes how to start a GNUnet peer. It assumes that you |
3404 | already compiled and installed GNUnet and its' dependencies. Before you start a | 3489 | have already compiled and installed GNUnet and its' dependencies. |
3405 | GNUnet peer, you may want to create a configuration file using gnunet-setup | 3490 | Before you start a GNUnet peer, you may want to create a configuration |
3406 | (but you do not have to). Sane defaults should exist in your | 3491 | file using gnunet-setup (but you do not have to). |
3407 | @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice you could | 3492 | Sane defaults should exist in your |
3408 | simply start without any configuration. If you want to configure your peer | 3493 | @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice |
3409 | later, you need to stop it before invoking the @code{gnunet-setup} tool to | 3494 | you could simply start without any configuration. If you want to |
3410 | customize further and to test your configuration (@code{gnunet-setup} has | 3495 | configure your peer later, you need to stop it before invoking the |
3411 | build-in test functions). | 3496 | @code{gnunet-setup} tool to customize further and to test your |
3412 | 3497 | configuration (@code{gnunet-setup} has build-in test functions). | |
3413 | The most important option you might have to still set by hand is in [PATHS]. | 3498 | |
3414 | Here, you use the option "GNUNET_HOME" to specify the path where GNUnet should | 3499 | The most important option you might have to still set by hand is in |
3415 | store its data. It defaults to @code{$HOME/}, which again should work for most | 3500 | [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where |
3416 | users. Make sure that the directory specified as GNUNET_HOME is writable to | 3501 | GNUnet should store its data. |
3502 | It defaults to @code{$HOME/}, which again should work for most users. | ||
3503 | Make sure that the directory specified as GNUNET_HOME is writable to | ||
3417 | the user that you will use to run GNUnet (note that you can run frontends | 3504 | the user that you will use to run GNUnet (note that you can run frontends |
3418 | using other users, GNUNET_HOME must only be accessible to the user used to run | 3505 | using other users, GNUNET_HOME must only be accessible to the user used to |
3419 | the background processes). | 3506 | run the background processes). |
3420 | 3507 | ||
3421 | You will also need to make one central decision: should all of GNUnet be run | 3508 | You will also need to make one central decision: should all of GNUnet be |
3422 | under your normal UID, or do you want distinguish between system-wide | 3509 | run under your normal UID, or do you want distinguish between system-wide |
3423 | (user-independent) GNUnet services and personal GNUnet services. The multi-user | 3510 | (user-independent) GNUnet services and personal GNUnet services. The |
3424 | setup is slightly more complicated, but also more secure and generally | 3511 | multi-user setup is slightly more complicated, but also more secure and |
3425 | recommended. | 3512 | generally recommended. |
3426 | 3513 | ||
3427 | @menu | 3514 | @menu |
3428 | * The Single-User Setup:: | 3515 | * The Single-User Setup:: |
@@ -3434,108 +3521,136 @@ recommended. | |||
3434 | @node The Single-User Setup | 3521 | @node The Single-User Setup |
3435 | @subsection The Single-User Setup | 3522 | @subsection The Single-User Setup |
3436 | 3523 | ||
3437 | For the single-user setup, you do not need to do anything special and can just | 3524 | For the single-user setup, you do not need to do anything special and can |
3438 | start the GNUnet background processes using @code{gnunet-arm}. By default, | 3525 | just start the GNUnet background processes using @code{gnunet-arm}. |
3439 | GNUnet looks in @file{~/.config/gnunet.conf} for a configuration (or | 3526 | By default, GNUnet looks in @file{~/.config/gnunet.conf} for a |
3440 | @code{$XDG_CONFIG_HOME/gnunet.conf} if@ @code{$XDG_CONFIG_HOME} is defined). If your | 3527 | configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ |
3441 | configuration lives elsewhere, you need to pass the @code{-c FILENAME} option | 3528 | @code{$XDG_CONFIG_HOME} is defined). If your configuration lives |
3442 | to all GNUnet commands. | 3529 | elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet |
3530 | commands. | ||
3443 | 3531 | ||
3444 | Assuming the configuration file is called @file{~/.config/gnunet.conf}, you | 3532 | Assuming the configuration file is called @file{~/.config/gnunet.conf}, |
3445 | start your peer using the @code{gnunet-arm} command (say as user | 3533 | you start your peer using the @code{gnunet-arm} command (say as user |
3446 | @code{gnunet}) using: | 3534 | @code{gnunet}) using: |
3535 | |||
3447 | @example | 3536 | @example |
3448 | gnunet-arm -c ~/.config/gnunet.conf -s | 3537 | gnunet-arm -c ~/.config/gnunet.conf -s |
3449 | @end example | 3538 | @end example |
3450 | 3539 | ||
3540 | @noindent | ||
3451 | The "-s" option here is for "start". The command should return almost | 3541 | The "-s" option here is for "start". The command should return almost |
3452 | instantly. If you want to stop GNUnet, you can use: | 3542 | instantly. If you want to stop GNUnet, you can use: |
3543 | |||
3453 | @example | 3544 | @example |
3454 | gnunet-arm -c ~/.config/gnunet.conf -e | 3545 | gnunet-arm -c ~/.config/gnunet.conf -e |
3455 | @end example | 3546 | @end example |
3456 | 3547 | ||
3548 | @noindent | ||
3457 | The "-e" option here is for "end". | 3549 | The "-e" option here is for "end". |
3458 | 3550 | ||
3459 | Note that this will only start the basic peer, no actual applications will be | 3551 | Note that this will only start the basic peer, no actual applications |
3460 | available. If you want to start the file-sharing service, use (after starting | 3552 | will be available. |
3553 | If you want to start the file-sharing service, use (after starting | ||
3461 | GNUnet): | 3554 | GNUnet): |
3555 | |||
3462 | @example | 3556 | @example |
3463 | gnunet-arm -c ~/.config/gnunet.conf -i fs | 3557 | gnunet-arm -c ~/.config/gnunet.conf -i fs |
3464 | @end example | 3558 | @end example |
3465 | 3559 | ||
3560 | @noindent | ||
3466 | The "-i fs" option here is for "initialize" the "fs" (file-sharing) | 3561 | The "-i fs" option here is for "initialize" the "fs" (file-sharing) |
3467 | application. You can also selectively kill only file-sharing support using | 3562 | application. You can also selectively kill only file-sharing support using |
3563 | |||
3468 | @example | 3564 | @example |
3469 | gnunet-arm -c ~/.config/gnunet.conf -k fs | 3565 | gnunet-arm -c ~/.config/gnunet.conf -k fs |
3470 | @end example | 3566 | @end example |
3471 | 3567 | ||
3568 | @noindent | ||
3472 | Assuming that you want certain services (like file-sharing) to be always | 3569 | Assuming that you want certain services (like file-sharing) to be always |
3473 | automatically started whenever you start GNUnet, you can activate them by | 3570 | automatically started whenever you start GNUnet, you can activate them by |
3474 | setting "FORCESTART=YES" in the respective section of the configuration file | 3571 | setting "FORCESTART=YES" in the respective section of the configuration |
3475 | (for example, "[fs]"). Then GNUnet with file-sharing support would be started | 3572 | file (for example, "[fs]"). Then GNUnet with file-sharing support would |
3476 | whenever you@ enter: | 3573 | be started whenever you@ enter: |
3574 | |||
3477 | @example | 3575 | @example |
3478 | gnunet-arm -c ~/.config/gnunet.conf -s | 3576 | gnunet-arm -c ~/.config/gnunet.conf -s |
3479 | @end example | 3577 | @end example |
3480 | 3578 | ||
3579 | @noindent | ||
3481 | Alternatively, you can combine the two options: | 3580 | Alternatively, you can combine the two options: |
3581 | |||
3482 | @example | 3582 | @example |
3483 | gnunet-arm -c ~/.config/gnunet.conf -s -i fs | 3583 | gnunet-arm -c ~/.config/gnunet.conf -s -i fs |
3484 | @end example | 3584 | @end example |
3485 | 3585 | ||
3586 | @noindent | ||
3587 | Using @code{gnunet-arm} is also the preferred method for initializing | ||
3588 | GNUnet from @code{init}. | ||
3486 | 3589 | ||
3487 | Using @code{gnunet-arm} is also the preferred method for initializing GNUnet | 3590 | Finally, you should edit your @code{crontab} (using the @code{crontab} |
3488 | from @code{init}. | 3591 | command) and insert a line@ |
3489 | 3592 | ||
3490 | Finally, you should edit your @code{crontab} (using the @code{crontab} command) | ||
3491 | and insert a line@ | ||
3492 | @code{@ | 3593 | @code{@ |
3493 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s@ | 3594 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s@ |
3494 | }@ | 3595 | }@ |
3596 | |||
3495 | to automatically start your peer whenever your system boots. | 3597 | to automatically start your peer whenever your system boots. |
3496 | 3598 | ||
3497 | @node The Multi-User Setup | 3599 | @node The Multi-User Setup |
3498 | @subsection The Multi-User Setup | 3600 | @subsection The Multi-User Setup |
3499 | 3601 | ||
3500 | This requires you to create a user @code{gnunet} and an additional group | 3602 | This requires you to create a user @code{gnunet} and an additional group |
3501 | @code{gnunetdns}, prior to running @code{make install} during installation. | 3603 | @code{gnunetdns}, prior to running @code{make install} during |
3604 | installation. | ||
3502 | Then, you create a configuration file @file{/etc/gnunet.conf} which should | 3605 | Then, you create a configuration file @file{/etc/gnunet.conf} which should |
3503 | contain the lines:@ | 3606 | contain the lines:@ |
3504 | @code{@ | ||
3505 | [arm]@ | ||
3506 | SYSTEM_ONLY = YES@ | ||
3507 | USER_ONLY = NO@ | ||
3508 | }@ | ||
3509 | Then, perform the same steps to run GNUnet as in the per-user configuration, | ||
3510 | except as user @code{gnunet} (including the @code{crontab} installation). You | ||
3511 | may also want to run @code{gnunet-setup} to configure your peer (databases, | ||
3512 | etc.). Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you | ||
3513 | run @code{gnunet-setup} as user @code{gnunet}, you might need to change | ||
3514 | permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can | ||
3515 | write to the file (during setup). | ||
3516 | |||
3517 | Afterwards, you need to perform another setup step for each normal user account | ||
3518 | from which you want to access GNUnet. First, grant the normal user | ||
3519 | (@code{$USER}) permission to the group gnunet:@ | ||
3520 | @code{@ | ||
3521 | # adduser $USER gnunet@ | ||
3522 | }@ | ||
3523 | Then, create a configuration file in @file{~/.config/gnunet.conf} for the $USER | ||
3524 | with the lines:@ | ||
3525 | @code{@ | ||
3526 | [arm]@ | ||
3527 | SYSTEM_ONLY = NO@ | ||
3528 | USER_ONLY = YES@ | ||
3529 | }@ | ||
3530 | This will ensure that @code{gnunet-arm} when started by the normal user will | ||
3531 | only run services that are per-user, and otherwise rely on the system-wide | ||
3532 | services. Note that the normal user may run gnunet-setup, but the | ||
3533 | configuration would be ineffective as the system-wide services will use | ||
3534 | @code{/etc/gnunet.conf} and ignore options set by individual users. | ||
3535 | 3607 | ||
3536 | Again, each user should then start the peer using @code{gnunet-arm -s} --- and | 3608 | @example |
3537 | strongly consider adding logic to start the peer automatically to their | 3609 | [arm]@ |
3538 | crontab. | 3610 | SYSTEM_ONLY = YES@ |
3611 | USER_ONLY = NO@ | ||
3612 | @end example | ||
3613 | |||
3614 | @noindent | ||
3615 | Then, perform the same steps to run GNUnet as in the per-user | ||
3616 | configuration, except as user @code{gnunet} (including the | ||
3617 | @code{crontab} installation). | ||
3618 | You may also want to run @code{gnunet-setup} to configure your peer | ||
3619 | (databases, etc.). | ||
3620 | Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you | ||
3621 | run @code{gnunet-setup} as user @code{gnunet}, you might need to change | ||
3622 | permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can | ||
3623 | write to the file (during setup). | ||
3624 | |||
3625 | Afterwards, you need to perform another setup step for each normal user | ||
3626 | account from which you want to access GNUnet. First, grant the normal user | ||
3627 | (@code{$USER}) permission to the group gnunet: | ||
3628 | |||
3629 | @example | ||
3630 | # adduser $USER gnunet | ||
3631 | @end example | ||
3632 | |||
3633 | @noindent | ||
3634 | Then, create a configuration file in @file{~/.config/gnunet.conf} for the | ||
3635 | $USER with the lines: | ||
3636 | |||
3637 | @example | ||
3638 | [arm]@ | ||
3639 | SYSTEM_ONLY = NO@ | ||
3640 | USER_ONLY = YES@ | ||
3641 | @end example | ||
3642 | |||
3643 | @noindent | ||
3644 | This will ensure that @code{gnunet-arm} when started by the normal user | ||
3645 | will only run services that are per-user, and otherwise rely on the | ||
3646 | system-wide services. | ||
3647 | Note that the normal user may run gnunet-setup, but the | ||
3648 | configuration would be ineffective as the system-wide services will use | ||
3649 | @code{/etc/gnunet.conf} and ignore options set by individual users. | ||
3650 | |||
3651 | Again, each user should then start the peer using | ||
3652 | @code{gnunet-arm -s} --- and strongly consider adding logic to start | ||
3653 | the peer automatically to their crontab. | ||
3539 | 3654 | ||
3540 | Afterwards, you should see two (or more, if you have more than one USER) | 3655 | Afterwards, you should see two (or more, if you have more than one USER) |
3541 | @code{gnunet-service-arm} processes running in your system. | 3656 | @code{gnunet-service-arm} processes running in your system. |
@@ -3543,61 +3658,67 @@ Afterwards, you should see two (or more, if you have more than one USER) | |||
3543 | @node Killing GNUnet services | 3658 | @node Killing GNUnet services |
3544 | @subsection Killing GNUnet services | 3659 | @subsection Killing GNUnet services |
3545 | 3660 | ||
3546 | It is not necessary to stop GNUnet services explicitly when shutting down your | 3661 | It is not necessary to stop GNUnet services explicitly when shutting |
3547 | computer. | 3662 | down your computer. |
3548 | 3663 | ||
3549 | It should be noted that manually killing "most" of the @code{gnunet-service} | 3664 | It should be noted that manually killing "most" of the |
3550 | processes is generally not a successful method for stopping a peer (since | 3665 | @code{gnunet-service} processes is generally not a successful method for |
3551 | @code{gnunet-service-arm} will instantly restart them). The best way to | 3666 | stopping a peer (since @code{gnunet-service-arm} will instantly restart |
3552 | explicitly stop a peer is using @code{gnunet-arm -e}; note that the per-user | 3667 | them). The best way to explicitly stop a peer is using |
3553 | services may need to be terminated before the system-wide services will | 3668 | @code{gnunet-arm -e}; note that the per-user services may need to be |
3554 | terminate normally. | 3669 | terminated before the system-wide services will terminate normally. |
3555 | 3670 | ||
3556 | @node Access Control for GNUnet | 3671 | @node Access Control for GNUnet |
3557 | @subsection Access Control for GNUnet | 3672 | @subsection Access Control for GNUnet |
3558 | 3673 | ||
3559 | This chapter documents how we plan to make access control work within the | 3674 | This chapter documents how we plan to make access control work within the |
3560 | GNUnet system for a typical peer. It should be read as a best-practice | 3675 | GNUnet system for a typical peer. It should be read as a best-practice |
3561 | installation guide for advanced users and builders of binary distributions. The | 3676 | installation guide for advanced users and builders of binary |
3562 | recommendations in this guide apply to POSIX-systems with full support for UNIX | 3677 | distributions. The recommendations in this guide apply to POSIX-systems |
3563 | domain sockets only. | 3678 | with full support for UNIX domain sockets only. |
3564 | 3679 | ||
3565 | Note that this is an advanced topic. The discussion presumes a very good | 3680 | Note that this is an advanced topic. The discussion presumes a very good |
3566 | understanding of users, groups and file permissions. Normal users on hosts with | 3681 | understanding of users, groups and file permissions. Normal users on |
3567 | just a single user can just install GNUnet under their own account (and | 3682 | hosts with just a single user can just install GNUnet under their own |
3568 | possibly allow the installer to use SUDO to grant additional permissions for | 3683 | account (and possibly allow the installer to use SUDO to grant additional |
3569 | special GNUnet tools that need additional rights). The discussion below largely | 3684 | permissions for special GNUnet tools that need additional rights). |
3570 | applies to installations where multiple users share a system and to | 3685 | The discussion below largely applies to installations where multiple users |
3571 | installations where the best possible security is paramount. | 3686 | share a system and to installations where the best possible security is |
3687 | paramount. | ||
3572 | 3688 | ||
3573 | A typical GNUnet system consists of components that fall into four categories: | 3689 | A typical GNUnet system consists of components that fall into four |
3690 | categories: | ||
3574 | 3691 | ||
3575 | @table @asis | 3692 | @table @asis |
3576 | 3693 | ||
3577 | @item User interfaces | 3694 | @item User interfaces |
3578 | User interfaces are not security sensitive and are supposed to be run and used | 3695 | User interfaces are not security sensitive and are supposed to be run and |
3579 | by normal system users. The GTK GUIs and most command-line programs fall into | 3696 | used by normal system users. |
3580 | this category. Some command-line tools (like gnunet-transport) should be | 3697 | The GTK GUIs and most command-line programs fall into this category. |
3581 | excluded as they offer low-level access that normal users should not need. | 3698 | Some command-line tools (like gnunet-transport) should be excluded as they |
3699 | offer low-level access that normal users should not need. | ||
3582 | @item System services and support tools | 3700 | @item System services and support tools |
3583 | System services should always run and offer services that can then be accessed | 3701 | System services should always run and offer services that can then be |
3584 | by the normal users. System services do not require special permissions, but as | 3702 | accessed by the normal users. |
3585 | they are not specific to a particular user, they probably should not run as a | 3703 | System services do not require special permissions, but as they are not |
3586 | particular user. Also, there should typically only be one GNUnet peer per host. | 3704 | specific to a particular user, they probably should not run as a |
3587 | System services include the gnunet-service and gnunet-daemon programs; support | 3705 | particular user. Also, there should typically only be one GNUnet peer per |
3588 | tools include command-line programs such as gnunet-arm. | 3706 | host. System services include the gnunet-service and gnunet-daemon |
3707 | programs; support tools include command-line programs such as gnunet-arm. | ||
3589 | @item Priviledged helpers | 3708 | @item Priviledged helpers |
3590 | Some GNUnet components require root rights to open raw sockets or perform other | 3709 | Some GNUnet components require root rights to open raw sockets or perform |
3591 | special operations. These gnunet-helper binaries are typically installed SUID | 3710 | other special operations. These gnunet-helper binaries are typically |
3592 | and run from services or daemons. | 3711 | installed SUID and run from services or daemons. |
3593 | @item Critical services | 3712 | @item Critical services |
3594 | Some GNUnet services (such as the DNS service) can manipulate the service in | 3713 | Some GNUnet services (such as the DNS service) can manipulate the service |
3595 | deep and possibly highly security sensitive ways. For example, the DNS service | 3714 | in deep and possibly highly security sensitive ways. For example, the DNS |
3596 | can be used to intercept and alter any DNS query originating from the local | 3715 | service can be used to intercept and alter any DNS query originating from |
3597 | machine. Access to the APIs of these critical services and their priviledged | 3716 | the local machine. Access to the APIs of these critical services and their |
3598 | helpers must be tightly controlled. | 3717 | priviledged helpers must be tightly controlled. |
3599 | @end table | 3718 | @end table |
3600 | 3719 | ||
3720 | @c FIXME: The titles of these chapters are too long in the index. | ||
3721 | |||
3601 | @menu | 3722 | @menu |
3602 | * Recommendation - Disable access to services via TCP:: | 3723 | * Recommendation - Disable access to services via TCP:: |
3603 | * Recommendation - Run most services as system user "gnunet":: | 3724 | * Recommendation - Run most services as system user "gnunet":: |
@@ -3610,76 +3731,85 @@ helpers must be tightly controlled. | |||
3610 | @node Recommendation - Disable access to services via TCP | 3731 | @node Recommendation - Disable access to services via TCP |
3611 | @subsubsection Recommendation - Disable access to services via TCP | 3732 | @subsubsection Recommendation - Disable access to services via TCP |
3612 | 3733 | ||
3613 | GNUnet services allow two types of access: via TCP socket or via UNIX domain | 3734 | GNUnet services allow two types of access: via TCP socket or via UNIX |
3614 | socket. If the service is available via TCP, access control can only be | 3735 | domain socket. |
3615 | implemented by restricting connections to a particular range of IP addresses. | 3736 | If the service is available via TCP, access control can only be |
3616 | This is acceptable for non-critical services that are supposed to be available | 3737 | implemented by restricting connections to a particular range of IP |
3617 | to all users on the local system or local network. However, as TCP is generally | 3738 | addresses. |
3618 | less efficient and it is rarely the case that a single GNUnet peer is supposed | 3739 | This is acceptable for non-critical services that are supposed to be |
3619 | to serve an entire local network, the default configuration should disable TCP | 3740 | available to all users on the local system or local network. |
3620 | access to all GNUnet services on systems with support for UNIX domain sockets. | 3741 | However, as TCP is generally less efficient and it is rarely the case |
3742 | that a single GNUnet peer is supposed to serve an entire local network, | ||
3743 | the default configuration should disable TCP access to all GNUnet | ||
3744 | services on systems with support for UNIX domain sockets. | ||
3621 | As of GNUnet 0.9.2, configuration files with TCP access disabled should be | 3745 | As of GNUnet 0.9.2, configuration files with TCP access disabled should be |
3622 | generated by default. Users can re-enable TCP access to particular services | 3746 | generated by default. Users can re-enable TCP access to particular |
3623 | simply by specifying a non-zero port number in the section of the respective | 3747 | services simply by specifying a non-zero port number in the section of |
3624 | service. | 3748 | the respective service. |
3625 | 3749 | ||
3626 | 3750 | ||
3627 | @node Recommendation - Run most services as system user "gnunet" | 3751 | @node Recommendation - Run most services as system user "gnunet" |
3628 | @subsubsection Recommendation - Run most services as system user "gnunet" | 3752 | @subsubsection Recommendation - Run most services as system user "gnunet" |
3629 | 3753 | ||
3630 | GNUnet's main services should be run as a separate user "gnunet" in a special | 3754 | GNUnet's main services should be run as a separate user "gnunet" in a |
3631 | group "gnunet". The user "gnunet" should start the peer using "gnunet-arm -s" | 3755 | special group "gnunet". |
3632 | during system startup. The home directory for this user should be | 3756 | The user "gnunet" should start the peer using "gnunet-arm -s" during |
3633 | @file{/var/lib/gnunet} and the configuration file should be @file{/etc/gnunet.conf}. | 3757 | system startup. The home directory for this user should be |
3634 | Only the @code{gnunet} user should have the right to access @file{/var/lib/gnunet} | 3758 | @file{/var/lib/gnunet} and the configuration file should be |
3635 | (@emph{mode: 700}). | 3759 | @file{/etc/gnunet.conf}. |
3760 | Only the @code{gnunet} user should have the right to access | ||
3761 | @file{/var/lib/gnunet} (@emph{mode: 700}). | ||
3636 | 3762 | ||
3637 | @node Recommendation - Control access to services using group "gnunet" | 3763 | @node Recommendation - Control access to services using group "gnunet" |
3638 | @subsubsection Recommendation - Control access to services using group "gnunet" | 3764 | @subsubsection Recommendation - Control access to services using group "gnunet" |
3639 | 3765 | ||
3640 | Users that should be allowed to use the GNUnet peer should be added to the | 3766 | Users that should be allowed to use the GNUnet peer should be added to the |
3641 | group "gnunet". Using GNUnet's access control mechanism for UNIX domain | 3767 | group "gnunet". Using GNUnet's access control mechanism for UNIX domain |
3642 | sockets, those services that are considered useful to ordinary users should be | 3768 | sockets, those services that are considered useful to ordinary users |
3643 | made available by setting "UNIX_MATCH_GID=YES" for those services. Again, as | 3769 | should be made available by setting "UNIX_MATCH_GID=YES" for those |
3644 | shipped, GNUnet provides reasonable defaults. Permissions to access the | 3770 | services. |
3645 | transport and core subsystems might additionally be granted without necessarily | 3771 | Again, as shipped, GNUnet provides reasonable defaults. |
3646 | causing security concerns. Some services, such as DNS, must NOT be made | 3772 | Permissions to access the transport and core subsystems might additionally |
3647 | accessible to the "gnunet" group (and should thus only be accessible to the | 3773 | be granted without necessarily causing security concerns. |
3648 | "gnunet" user and services running with this UID). | 3774 | Some services, such as DNS, must NOT be made accessible to the "gnunet" |
3775 | group (and should thus only be accessible to the "gnunet" user and | ||
3776 | services running with this UID). | ||
3649 | 3777 | ||
3650 | @node Recommendation - Limit access to certain SUID binaries by group "gnunet" | 3778 | @node Recommendation - Limit access to certain SUID binaries by group "gnunet" |
3651 | @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" | 3779 | @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" |
3652 | 3780 | ||
3653 | Most of GNUnet's SUID binaries should be safe even if executed by normal users. | 3781 | Most of GNUnet's SUID binaries should be safe even if executed by normal |
3654 | However, it is possible to reduce the risk a little bit more by making these | 3782 | users. However, it is possible to reduce the risk a little bit more by |
3655 | binaries owned by the group "gnunet" and restricting their execution to user of | 3783 | making these binaries owned by the group "gnunet" and restricting their |
3656 | the group "gnunet" as well (4750). | 3784 | execution to user of the group "gnunet" as well (4750). |
3657 | 3785 | ||
3658 | @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | 3786 | @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" |
3659 | @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | 3787 | @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" |
3660 | 3788 | ||
3661 | A special group "gnunetdns" should be created for controlling access to the | 3789 | A special group "gnunetdns" should be created for controlling access to |
3662 | "gnunet-helper-dns". The binary should then be owned by root and be in group | 3790 | the "gnunet-helper-dns". |
3663 | "gnunetdns" and be installed SUID and only be group-executable (2750). Note | 3791 | The binary should then be owned by root and be in group "gnunetdns" and |
3664 | that the group "gnunetdns" should have no users in it at all, ever. The | 3792 | be installed SUID and only be group-executable (2750). |
3665 | "gnunet-service-dns" program should be executed by user "gnunet" (via | 3793 | @b{Note that the group "gnunetdns" should have no users in it at all, |
3794 | ever.} | ||
3795 | The "gnunet-service-dns" program should be executed by user "gnunet" (via | ||
3666 | gnunet-service-arm) with the binary owned by the user "root" and the group | 3796 | gnunet-service-arm) with the binary owned by the user "root" and the group |
3667 | "gnunetdns" and be SGID (2700). This way, @strong{only} "gnunet-service-dns" | 3797 | "gnunetdns" and be SGID (2700). This way, @strong{only} |
3668 | can change its group to "gnunetdns" and execute the helper, and the helper can | 3798 | "gnunet-service-dns" can change its group to "gnunetdns" and execute the |
3669 | then run as root (as per SUID). Access to the API offered by | 3799 | helper, and the helper can then run as root (as per SUID). |
3670 | "gnunet-service-dns" is in turn restricted to the user "gnunet" (not the | 3800 | Access to the API offered by "gnunet-service-dns" is in turn restricted |
3671 | group!), which means that only "benign" services can manipulate DNS queries | 3801 | to the user "gnunet" (not the group!), which means that only |
3672 | using "gnunet-service-dns". | 3802 | "benign" services can manipulate DNS queries using "gnunet-service-dns". |
3673 | 3803 | ||
3674 | @node Differences between "make install" and these recommendations | 3804 | @node Differences between "make install" and these recommendations |
3675 | @subsubsection Differences between "make install" and these recommendations | 3805 | @subsubsection Differences between "make install" and these recommendations |
3676 | 3806 | ||
3677 | The current build system does not set all permissions automatically based on | 3807 | The current build system does not set all permissions automatically based |
3678 | the recommendations above. In particular, it does not use the group "gnunet" at | 3808 | on the recommendations above. In particular, it does not use the group |
3679 | all (so setting gnunet-helpers other than the gnunet-helper-dns to be owned by | 3809 | "gnunet" at all (so setting gnunet-helpers other than the |
3680 | group "gnunet" must be done manually). Furthermore, 'make install' will | 3810 | gnunet-helper-dns to be owned by group "gnunet" must be done manually). |
3681 | silently fail to set the DNS binaries to be owned by group "gnunetdns" unless | 3811 | Furthermore, 'make install' will silently fail to set the DNS binaries to |
3682 | that group already exists (!). An alternative name for the "gnunetdns" group | 3812 | be owned by group "gnunetdns" unless that group already exists (!). |
3683 | can be specified using the "--with-gnunetdns=GRPNAME" configure | 3813 | An alternative name for the "gnunetdns" group can be specified using the |
3684 | option. | 3814 | "--with-gnunetdns=GRPNAME" configure option. |
3685 | 3815 | ||