New upstream version 1.3.0~rc3upstream/1.3.0_rc3

1 files changed, 75 insertions, 87 deletions

diff --git a/doc/running.texi b/doc/running.texi
index bee48f3..aa5b93c 100644
--- a/doc/running.texi
+++ b/doc/running.texi
@@ -2,90 +2,85 @@
 @chapter Running Knot DNS
 
 @menu
-* Running a slave server::       
-* Running a master server::       
-* Controlling running daemon::       
+* Running a slave server::
+* Running a master server::
+* Controlling running daemon::
 @end menu
 
-Knot DNS is designed to compile zone files before loading them into server.
-The reason for this is to speed up server startup, but requires a bit of user
-effort, so each time the zone file changes you need to compile it.
+Knot DNS can run either in the foreground or in a background, with the @code{-d}
+option. When run in foreground, it doesn't create a PID file. Other than that,
+there are no differences and you can control it just the same way.
 @example
-$ knotc -c knot.conf compile
+Usage: knotd [parameters]
+
+Parameters:
+ -c, --config [file] Select configuration file.
+ -d, --daemonize     Run server as a daemon.
+ -v, --verbose       Verbose mode - additional runtime information.
+ -V, --version       Print version of the server.
+ -h, --help          Print help and usage.
 @end example
-Knot DNS automatically compiles zones on some actions (@code{start|restart}).
+
+Use knotc tool for convenience when working with the server daemon.
+As of Knot DNS 1.3.0, the zones are not compiled anymore. That makes working
+with the server much more user friendly.
 @example
-$ knotc -c knot.conf start|reload|restart
+$ knotc -c knot.conf reload|restart
 @end example
 
 The tool @code{knotc} is designed as a front-end for user, making it easier
-to do everything from zone compilation to controlling the server daemon.
+to do everything from server startup to state checking of a running server daemon.
 If you want to control the daemon directly, use @code{SIGINT} to quit the process or @code{SIGHUP} to reload configuration.
 
 @example
 Usage: knotc [parameters] <action> [action_args]
 
 Parameters:
- -c [file], --config=[file]	Select configuration file.
- -j [num], --jobs=[num]    	Number of parallel tasks to run when compiling.
- -s [server]               	Remote server address (default 127.0.0.1)
- -p [port]                 	Remote server port (default 5553)
- -y [hmac:]name:key]       	Use key_id specified on the command line.
- -k [file]                 	Use key file (as in config section 'keys').
-                           	  f.e. echo "knotc-key hmac-md5 Wg==" > knotc.key
- -f, --force               	Force operation - override some checks.
- -v, --verbose             	Verbose mode - additional runtime information.
- -V, --version             	Print knot server version.
- -w, --wait                	Wait for the server to finish start/stop operations.
- -i, --interactive         	Interactive mode (do not daemonize).
- -h, --help                	Print help and usage.
+ -c [file], --config=[file] Select configuration file.
+ -s [server]                Remote UNIX socket/IP address (default $@{rundir@}/knot.sock).
+ -p [port]                  Remote server port (only for IP).
+ -y [[hmac:]name:key]       Use key_id specified on the command line.
+ -k [file]                  Use key file (as in config section 'keys').
+                              Example:
+                              echo "knotc-key hmac-md5 Wg==" > knotc.key
+ -f, --force                Force operation - override some checks.
+ -v, --verbose              Verbose mode - additional runtime
+                            information.
+ -V, --version              Print knot server version.
+ -w, --wait                 Wait for the server to finish start/stop
+                            operations.
+ -i, --interactive          Interactive mode (do not daemonize).
+ -h, --help                 Print help and usage.
 
 Actions:
- start				Start server (no-op if running).
- stop				Stop server (no-op if running).
- restart			Restarts server (no-op if running).
- reload				Reloads configuration and changed zones.
- refresh			Refresh slave zones (all if not specified).
- flush				Flush journal and update zone files.
- status				Check if server is running.
- zonestatus			Show status of configured zones.
- checkconf			Check server configuration.
- checkzone			Check specified zone files.
- compile			Compile zone files (all if not specified).
-@end example
-
-If you want to run Knot DNS daemon directly, you can use @code{knotd} binary
-to do that. It accepts just configuration file and option to run in background.
-@example
-Usage: knotd [parameters]
-
-Parameters:
- -c, --config [file] Select configuration file.
- -d, --daemonize     Run server as a daemon.
- -v, --verbose       Verbose mode - additional runtime information.
- -V, --version       Print version of the server.
- -h, --help          Print help and usage.
+ start                      Start server (if not running).
+ stop                       Stop server.
+ restart                    Restart server.
+ reload                     Reload configuration and changed zones.
+ refresh [zone]             Refresh slave zone (all if not specified).
+ flush                      Flush journal and update zone files.
+ status                     Check if server is running.
+ zonestatus                 Show status of configured zones.
+ checkconf                  Check current server configuration.
+ checkzone [zone]           Check zone (all if not specified).
+ memstats [zone]            Estimate memory consumption for zone (all if not specified).
 @end example
 
 Also, the server needs to create several files in order to run properly.
-All files are placed in the directory described by @code{storage} (@pxref{storage}).
-PID file can be placed elsewhere using the @code{pidfile} statement (@pxref{pidfile}).
-Slave zones with relative path specified will be placed in the @code{storage} as well.
+Zones and related data are stored in the directory described by @code{storage} (@pxref{storage}).
 @itemize @bullet
 @item
-@emph{Compiled zones} - preprocessed zones, for example zone @code{example.com} will be
-placed in @file{STORAGE/example.com.db}.
-@item
 @emph{Journal files} - each zone has a journal file to store differences for IXFR and
 dynamic updates. Journal for zone @code{example.com} will be
 placed in @file{STORAGE/example.com.diff.db}.
+
 @item
-@emph{PID file} - unless specified differently by the @code{pidfile}, it will be placed
-in the @file{STORAGE/knot.pid}.
+@emph{PID file} - is created automatically in @code{rundir} (@pxref{rundir}) when
+the server is run in background.
+
 @item
-@emph{Checksum files} - in order to identify compiled zone corruption, it
-has a separate checksum file. For @code{example.com} will be
-placed in @file{STORAGE/example.com.db.crc}.
+@emph{Control sockets} - as a default, UNIX sockets are created in @code{rundir} (@pxref{rundir}),
+but can be overriden.
 @end itemize
 
 @node Running a slave server
@@ -93,29 +88,26 @@ placed in @file{STORAGE/example.com.db.crc}.
 
 Running the server as a slave is very straightforward as you usually bootstrap
 zones over AXFR and thus avoid any manual zone compilation.
-When a zone is transferred over AXFR, both the compiled zone and the zone file is
-updated, so no further compilation is needed.
-However when IXFR transfer finishes, it stores the differences in a journal file
-and doesn't update the zone file nor compiled zone immediately,
-but there is a timer that checks periodically for new differences and
-updates both zone file and the compiled zone. You can configure this timer
+In contrast to AXFR, when the incremental transfer finishes, it stores the differences in a journal file
+and doesn't update the zone file immediately.
+There is a timer that checks periodically for new differences and
+updates the zone file. You can configure this timer
 with the @code{zonefile-sync} statement in @code{zones} (@pxref{zones}).
 
-There are two ways to start the server - directly or with the @code{knotc} controller tool.
-First, let us start it directly. If you do not pass any configuration, it will try to
+There are two ways to start the server - in foreground or background.
+First, let's start in foreground. If you do not pass any configuration, it will try to
 search configuration in default path that is @code{SYSCONFDIR/knot.conf}. The @code{SYSCONFDIR}
 depends on what you passed to the @code{./configure}, usually @code{/etc}.
 
 @example
-$ knotc -c slave.conf checkconf # check configuration
 $ knotd -c slave.conf
 @end example
 
-However to start it as a daemon, @code{knotc} tool should be used.
-The @code{knotc} tool accepts parameter @code{-w} to wait until the requested operation finishes.
-When the action is "start" for example, it waits until the server starts to serve zones.
+To start it as a daemon, just add a @code{-d} parameter. Unlike the foreground mode,
+PID file will be created in @code{rundir} directory.
+
 @example
-$ knotc -w -c slave.conf start # start the daemon
+$ knotd -d -c slave.conf # start the daemon
 $ knotc -c slave.conf stop # stop the daemon
 @end example
 
@@ -124,50 +116,46 @@ When the server is running, you can control the daemon, see @ref{Controlling run
 @node Running a master server
 @section Running a master server
 
-Knot DNS first needs to compile the zones before it can load them, therefore you need to
-compile them with the @code{knotc compile} action.
-Some actions like @code{start} or @code{restart} compile zones automatically.
-
 If you want to just check the zone files first before starting,
 you can use @code{knotc checkzone} action.
 @example
 $ knotc -c master.conf checkzone example.com
 @end example
 
-Starting and stopping the daemon is the same as with the slave server in the previous section.
-@example
-$ knotc -c master.conf compile
-$ knotc -w -c master.conf start
-@end example
+For an approximate estimate of server's memory consumption, you can use the @code{knotc memstats} action.
+This action prints count of resource records, percentage of signed records and finally estimation
+of memory consumption for each zone, unless specified otherwise. Please note that estimated values might
+differ from the actual consumption. Also, for slave servers with incoming transfers enabled,
+be aware that the actual memory consumption might be double or more during transfers.
 
-Or you can compile it automatically:
 @example
-$ knotc -c master.conf checkconf # check configuration
-$ knotc -w -c master.conf start
+$ knotc -c master.conf memstats example.com
 @end example
 
+Starting and stopping the daemon is the same as with the slave server in the previous section.
+
 @node Controlling running daemon
 @section Controlling running daemon
 
 Knot DNS was designed to allow server reconfiguration on-the-fly without interrupting
 its operation. Thus it is possible to change both configuration and zone files and
 also add or remove zones without restarting the server. This can be done with the
-@code{knotc reload} action. 
+@code{knotc reload} action.
 
 @example
-$ knotc -c master.conf compile # compile updated zones
 $ knotc -c master.conf reload  # reconfigure and load updated zones
 @end example
 
 If you want @emph{IXFR-out} differences created from changes you make to a zone file, enable @ref{ixfr-from-differences}
-in @code{zones} statement, then compile the zone and reload your server as seen above.
+in @code{zones} statement, then reload your server as seen above.
 If @emph{SOA}'s @emph{serial} is not changed no differences will be created. Please note
 that this feature is in @emph{experimental} stage and should be used with care.
 If you encounter a bug using this feature, please send it to Knot developers (@pxref{Submitting a bugreport}).
 
 You can also choose to tear-down the server fully and restart with the @code{knotc restart} action.
+Note that some actions like start, stop and restart cannot be done remotely.
 @example
-$ knotc -c master.conf running # check if running
+$ knotc -c master.conf status # check if running
 $ knotc -c master.conf restart # fully restart
 @end example