Adding upstream version 4.5.upstream/4.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 200 insertions, 0 deletions

diff --git a/doc/installation.adoc b/doc/installation.adoc
new file mode 100644
index 0000000..b683911
--- /dev/null
+++ b/doc/installation.adoc
@@ -0,0 +1,200 @@
+// This file is part of chrony
+//
+// Copyright (C) Richard P. Curnow  1997-2003
+// Copyright (C) Miroslav Lichvar  2009-2016
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of version 2 of the GNU General Public License as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+= Installation
+
+The software is distributed as source code which has to be compiled. The source
+code is supplied in the form of a gzipped tar file, which unpacks to a
+subdirectory identifying the name and version of the program.
+
+A C compiler (e.g. `gcc` or `clang`) and GNU Make are needed to build `chrony`.
+The following libraries with their development files, and programs, are needed
+to enable optional features:
+
+* pkg-config: detection of development libraries
+* Nettle, GnuTLS, NSS, or LibTomCrypt: secure hash functions (`SECHASH`)
+* libcap: dropping root privileges on Linux (`DROPROOT`)
+* libseccomp: system call filter on Linux (`SCFILTER`)
+* GnuTLS and Nettle: Network Time Security (`NTS`)
+* Editline: line editing in `chronyc` (`READLINE`)
+* timepps.h header: PPS reference clock
+* Asciidoctor: documentation in HTML format
+* Bash: test suite
+
+The following programs are needed when building `chrony` from the git
+repository instead of a released tar file:
+
+* Asciidoctor: manual pages
+* Bison: parser for chronyc settime command
+
+After unpacking the source code, change directory into it, and type
+
+----
+./configure
+----
+
+This is a shell script that automatically determines the system type. There is
+an optional parameter `--prefix`, which indicates the directory tree where the
+software should be installed. For example,
+
+----
+./configure --prefix=/opt/free
+----
+
+will install the `chronyd` daemon into `/opt/free/sbin` and the `chronyc`
+control program into `/opt/free/bin`. The default value for the prefix is
+`/usr/local`.
+
+The `configure` script assumes you want to use `gcc` as your compiler. If you
+want to use a different compiler, you can configure this way:
+
+----
+CC=cc ./configure --prefix=/opt/free
+----
+
+for Bourne-family shells, or
+
+----
+setenv CC cc
+setenv CFLAGS -O
+./configure --prefix=/opt/free
+----
+
+for C-family shells.
+
+If the software cannot (yet) be built on your system, an error message will be
+shown. Otherwise, `Makefile` will be generated.
+
+On Linux, if development files for the libcap library are available, `chronyd`
+will be built with support for dropping root privileges. On other systems no
+extra library is needed. The default user which `chronyd` should run as can be
+specified with the `--with-user` option of the `configure` script.
+
+If development files for the POSIX threads library are available, `chronyd`
+will be built with support for asynchronous resolving of hostnames specified in
+the `server`, `peer`, and `pool` directives. This allows `chronyd` operating as
+a server to respond to client requests when resolving a hostname. If you don't
+want to enable the support, specify the `--disable-asyncdns` flag to
+`configure`.
+
+If development files for the https://www.lysator.liu.se/~nisse/nettle/[Nettle],
+https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS[NSS], or
+https://www.libtom.net/LibTomCrypt/[libtomcrypt] library are available,
+`chronyd` will be built with support for other cryptographic hash functions
+than MD5, which can be used for NTP authentication with a symmetric key. If you
+don't want to enable the support, specify the `--disable-sechash` flag to
+`configure`.
+
+If development files for the editline library are available,
+`chronyc` will be built with line editing support. If you don't want this,
+specify the `--disable-readline` flag to `configure`.
+
+If a `timepps.h` header is available (e.g. from the
+http://linuxpps.org[LinuxPPS project]), `chronyd` will be built with PPS API
+reference clock driver. If the header is installed in a location that isn't
+normally searched by the compiler, you can add it to the searched locations by
+setting the `CPPFLAGS` variable to `-I/path/to/timepps`.
+
+The `--help` option can be specified to `configure` to print all options
+supported by the script.
+
+Now type
+
+----
+make
+----
+
+to build the programs.
+
+If you want to build the manual in HTML, type
+
+----
+make docs
+----
+
+Once the programs have been successfully compiled, they need to be installed in
+their target locations. This step normally needs to be performed by the
+superuser, and requires the following command to be entered.
+
+----
+make install
+----
+
+This will install the binaries and man pages.
+
+To install the HTML version of the manual, enter the command
+
+----
+make install-docs
+----
+
+Now that the software is successfully installed, the next step is to set up a
+configuration file. The default location of the file is _/etc/chrony.conf_.
+Several examples of configuration with comments are included in the examples
+directory. Suppose you want to use public NTP servers from the pool.ntp.org
+project as your time reference. A minimal useful configuration file could be
+
+----
+pool pool.ntp.org iburst
+makestep 1.0 3
+rtcsync
+----
+
+Then, `chronyd` can be run. For security reasons, it's recommended to create an
+unprivileged user for `chronyd` and specify it with the `-u` command-line
+option or the `user` directive in the configuration file, or set the default
+user with the `--with-user` configure option before building.
+
+== Support for system call filtering
+
+`chronyd` can be built with support for the Linux secure computing (seccomp)
+facility. This requires development files for the
+https://github.com/seccomp/libseccomp[libseccomp] library and the
+`--enable-scfilter` option specified to `configure`. The `-F` option of
+`chronyd` will enable a system call filter, which should significantly reduce
+the kernel attack surface and possibly prevent kernel exploits from `chronyd`
+if it is compromised.
+
+== Extra options for package builders
+
+The `configure` and `make` procedures have some extra options that may be
+useful if you are building a distribution package for `chrony`.
+
+The `--mandir=DIR` option to `configure` specifies an installation directory
+for the man pages. This overrides the `man` subdirectory of the argument to the
+`--prefix` option.
+
+----
+./configure --prefix=/usr --mandir=/usr/share/man
+----
+
+to set both options together.
+
+The final option is the `DESTDIR` option to the `make` command. For example,
+you could use the commands
+
+----
+./configure --prefix=/usr --mandir=/usr/share/man
+make all docs
+make install DESTDIR=./tmp
+cd tmp
+tar cvf - . | gzip -9 > chrony.tar.gz
+----
+
+to build a package. When untarred within the root directory, this will install
+the files to the intended final locations.