Commit 025659c5 authored by Michal 'vorner' Vaner's avatar Michal 'vorner' Vaner
Browse files

Merge branch 'master' into work/grow

Conflicts:
	src/lib/datasrc/memory/zone_writer.cc
	src/lib/datasrc/tests/memory/Makefile.am
	src/lib/datasrc/tests/memory/zone_data_updater_unittest.cc
	src/lib/datasrc/tests/memory/zone_finder_unittest.cc
parents 4df6d159 066c983e
......@@ -14,6 +14,7 @@ Michael Graff
Michal Vaner
Mukund Sivaraman
Naoki Kambe
Paul Selkirk
Shane Kerr
Shen Tingting
Stephen Morris
......
613. [func] jinmei
datasrc: Error handling in loading zones into memory is now more
consistent and convenient: data source configuration does not fail
due to zones configured to be loaded into memory but not available
in the data source, just like the case of missing zone file for
the MasterFiles type of data source. Also, zones that aren't
loaded into memory due to errors can now be reloaded for b10-auth
using the bindctl Auth loadzone command after fixing the error,
without reconfiguring the entire data source.
(Trac #2851, git a3d4fe8a32003534150ed076ea0bbf80e1fcc43c)
612. [func] tomek
b10-dhcp6: Support for relayed DHCPv6 traffic has been added.
611. [func] naokikambe
Added Xfrin statistics items such as the number of successful
transfers. These are per-zone type counters. Their values can be
obtained with zone names by invoking "Stats show Xfrin" via bindctl
while Xfrin is running.
(Trac #2252, git e1a0ea8ef5c51b9b25afa111fbfe9347afbe5413)
bind10-1.0.0beta2 released on May 10, 2013
610. [bug] muks
When the sqlite3 program is not available on the system (in
PATH), we no longer attempt to run some tests which depend
on it.
(Trac #1909, git f85b274b85b57a094d33ca06dfbe12ae67bb47df)
609. [bug] jinmei
Handled some rare error cases in DNS server classes correctly.
This fix specifically solves occasional crash of b10-auth due to
errors caused by TCP DNS clients. Also, as a result of cleanups
with the fix, b10-auth should now be a little bit faster in
handling UDP queries: in some local experiments it ran about 5%
faster.
(Trac #2903, git 6d3e0f4b36a754248f8a03a29e2c36aef644cdcc)
608. [bug] jinmei
b10-cmdctl: fixed a hangup problem on receiving the shutdown
command from bindctl. Note, however, that cmdctl is defined as
a "needed" module by default, so shutting down cmdctl would cause
shutdown of the entire BIND 10 system anyway, and is therefore
still not very useful in practice.
(Trac #2712, git fa392e8eb391a17d30550d4b290c975710651d98)
607. [bug] jinmei
Worked around some unit test regressions on FreeBSD 9.1 due to
a binary compatibility issue between standard and system
libraries (http://www.freebsd.org/cgi/query-pr.cgi?pr=175453).
While not all tests still pass, main BIND 10 programs should
generally work correctly. Still, there can be odd run time
behavior such as abrupt crash instead of graceful shutdown
when some fatal event happens, so it's generally discouraged to
use BIND 10 on FreeBSD 9.1 RELEASE. According to the above
bug report for FreeBSD, it seems upgrading or downgrading the
FreeBSD version will solve this problem.
(Trac #2887, git 69dfb4544d9ded3c10cffbbfd573ae05fdeb771f)
606. [bug] jinmei
b10-xfrout now correctly stops sending notify requests once it
receives a valid response. It previously handled it as if the
requests are timed out and resent it a few times in a short
period.
(Trac #2879, git 4c45f29f28ae766a9f7dc3142859f1d0000284e1)
605. [bug] tmark
Modified perfdhcp to calculate the times displayed for packet sent
and received as time elapsed since perfdhcp process start time.
Previously these were times since the start of the epoch.
However the large numbers involved caused loss of precision
in the calculation of the test statistics.
(Trac #2785, git e9556924dcd1cf285dc358c47d65ed7c413e02cf)
604. [func] marcin
libdhcp++: abstracted methods which open sockets and send/receive
DHCP4 packets to a separate class. Other classes will be derived
from it to implement OS-specific methods of DHCPv4 packets filtering.
The primary purpose for this change is to add support for Direct
DHCPv4 response to a client which doesn't have an address yet on
different OSes.
(Trac #991, git 33ffc9a750cd3fb34158ef676aab6b05df0302e2)
603. [func] tmark
The directory in which the b10-dchp4 and b10-dhcp6 server id files has
been changed from the local state directory (set by the "configure"
--localstatedir switch) to the "bind10" subdirectory of it. After an
upgrade, server id files in the former location will be orphaned and
should be manually removed.
(Trac #2770, git a622140d411b3f07a68a1451e19df36118a80650)
602. [bug] tmark
Perfdhcp will now exit gracefully if the command line argument for
IP version (-4 or -6) does not match the command line argument
given for the server. Prior to this perfdhcp would core when given
an IP version of -6 but a valid IPv4 address for server.
(Trac #2784, git 96b66c0c79dccf9a0206a45916b9b23fe9b94f74)
601. [bug]* jinmei, vorner
The "delete record" interface of the database based data source
was extended so that the parameter includes reversed name in
addition to the actual name. This may help the underlying
accessor implementation if reversed names are more convenient
for the delete operation. This was the case for the SQLite3
accessor implementation, and it now performs delete operations
much faster. At a higher level, this means IXFR and DDNS Updates
to the sqlite3 database are no longer so slow on large zones as
they were before.
(Trac #2877, git 33bd949ac7288c61ed0a664b7329b50b36d180e5)
600. [bug] tmark
Changed mysql_lease_mgr to set the SQL mode option to STRICT. This
causes mysql it to treat invalid input data as an error. Rather than
"successfully" inserting a too large value by truncating it, the
insert will fail, and the lease manager will throw an exception.
Also, attempts to create a HWAddr (hardware address) object with
too long an array of data now throw an exception.
(Trac #2387, git cac02e9290600407bd6f3071c6654c1216278616)
599. [func] tomek
libdhcp++: Pkt6 class is now able to parse and build relayed DHCPv6
messages.
(Trac #2827, git 29c3f7f4e82d7e85f0f5fb692345fd55092796b4)
bind10-1.0.0beta1 released on April 4, 2013
598. [func]* jinmei
The separate "static" data source is now deprecated as it can be
served in the more generic "MasterFiles" type of data source.
This means existing configuration may not work after an update.
If "config show data_sources/classes/CH[0]" on bindctl contains a
"static" type of data source, you'll need to update it as follows:
> config set data_sources/classes/CH[0]/type MasterFiles
> config set data_sources/classes/CH[0]/params {"BIND": =>
"<the value of current data_sources/classes/CH[0]/params>"}
> config set data_sources/classes/CH[0]/cache-enable true
> config commit
(Same for CH[1], CH[2], IN[0], etc, if applicable, although it
should be very unlikely in practice. Also note: '=>' above
indicates the next line is actually part of the command. Do
not type in this "arrow").
(Part of Trac #2833, git 0363b4187fe3c1a148ad424af39e12846610d2d7)
597. [func] tmark
b10-dhcp6: Added unit tests for handling requests when no
IPv6 subnets are configured/defined. Testing these conditions
was overlooked during implementation of Trac #2719.
(Trac #2721, git ce7f53b2de60e2411483b4aa31c714763a36da64)
596. [bug] jinmei
Added special handling for the case where b10-auth receives a
NOTIFY message, but zonemgr isn't running. Previously this was
logged as a communications problem at the ERROR level, resulting
in increasing noise when zonemgr is intentionally stopped. Other
than the log level there is no change in externally visible
behavior.
(Trac #2562, git 119eed9938b17cbad3a74c823aa9eddb7cd337c2)
595. [bug] tomek
All DHCP components now gracefully refuse to handle too short
DUIDs and client-id.
(Trac #2723, git a043d8ecda6aff57922fe98a33c7c3f6155d5d64)
594. [func] muks, pselkirk
libdns++: the NSEC, DS, DLV, and AFSDB Rdata classes now use the
generic lexer in constructors from text. This means that the name
fields in such RRs in a zone file can now be non-absolute (the
origin name in that context will be used), e.g., when loaded by
b10-loadzone.
(Trac #2386, git dc0f34afb1eccc574421a802557198e6cd2363fa)
(Trac #2391, git 1450d8d486cba3bee8be46e8001d66898edd370c)
593. [func] jelte
Address + port output and logs is now consistent according to our
coding guidelines, e.g. <address>:<port> in the case of IPv4, and
[<address>]:<port> in the case of IPv6, instead of <address>#<port>
(Trac #1086, git bcefe1e95cdd61ee4a09b20522c3c56b315a1acc)
592. [bug] jinmei
b10-auth and zonemgr now handle some uncommon NOTIFY messages more
gracefully: auth immediately returns a NOTAUTH response if the
server does not have authority for the zone (the behavior
compatible with BIND 9) without bothering zonemgr; zonemgr now
simply skips retransfer if the specified zone is not in its
secondary zone list, instead of producing noisy error logs.
(Trac #1938, git 89d7de8e2f809aef2184b450e7dee1bfec98ad14)
591. [func] vorner
Ported the remaining tests from the old shell/perl based system to
lettuce. Make target `systest' is now gone. Currently, the lettuce
tests are in git only, not part of the release tarball.
(Trac #2624, git df1c5d5232a2ab551cd98b77ae388ad568a683ad)
590. [bug] tmark
Modified "include" statements in DHCP MySQL lease manager code to
fix build problems if MySQL is installed in a non-standard location.
(Trac #2825, git 4813e06cf4e0a9d9f453890557b639715e081eca)
589. [bug] jelte
b10-cmdctl now automatically re-reads the user accounts file when
it is updated.
(Trac #2710, git 16e8be506f32de668699e6954f5de60ca9d14ddf)
588. [bug]* jreed
b10-xfrout: Log message id XFROUT_QUERY_QUOTA_EXCCEEDED
changed to XFROUT_QUERY_QUOTA_EXCEEDED.
(git be41be890f1349ae4c870a887f7acd99ba1eaac5)
587. [bug] jelte
When used from python, the dynamic datasource factory now
explicitely loads the logging messages dictionary, so that correct
logging messages does not depend on incidental earlier import
statements. Also, the sqlite3-specific log messages have been moved
from the general datasource library to the sqlite3 datasource
(which also explicitely loads its messages).
(Trac #2746, git 1c004d95a8b715500af448683e4a07e9b66ea926)
586. [func] marcin
libdhcp++: Removed unnecesary calls to the function which
validates option definitions used to create instances of options
......
......@@ -2,7 +2,7 @@ ACLOCAL_AMFLAGS = -I m4macros -I examples/m4 ${ACLOCAL_FLAGS}
# ^^^^^^^^ This has to be the first line and cannot come later in this
# Makefile.am due to some bork in some versions of autotools.
SUBDIRS = compatcheck doc . src tests
SUBDIRS = compatcheck doc . src tests m4macros
USE_LCOV=@USE_LCOV@
LCOV=@LCOV@
GENHTML=@GENHTML@
......@@ -46,7 +46,7 @@ endif
clean-cpp-coverage:
@if [ $(USE_LCOV) = yes ] ; then \
$(LCOV) --directory . --zerocounters; \
rm -rf coverage/; \
rm -rf $(abs_top_srcdir)/coverage-cpp-html/; \
else \
echo "C++ code coverage not enabled at configuration time." ; \
echo "Use: ./configure --with-lcov" ; \
......@@ -115,11 +115,6 @@ cppcheck:
--template '{file}:{line}: check_fail: {message} ({severity},{id})' \
src
# system tests
systest:
cd tests/system; \
sh $(abs_srcdir)/tests/system/runall.sh
### include tool to generate documentation from log message specifications
### in the distributed tarball:
EXTRA_DIST = tools/system_messages.py
......
......@@ -25,6 +25,12 @@ the DHCPv4 and DHCPv6 servers must be considered experimental.
Limitations and known issues with this DHCP release can be found
at http://bind10.isc.org/wiki/KeaKnownIssues
NOTE: The API/ABI provided by libraries in BIND 10 may change in future
point releases. So please do not assume currently that any code that you
compile for a particular version of a BIND 10 library will work in
future versions of the library. We aim to stabilize the public API/ABI
interface of BIND 10 libraries in future releases.
Documentation is included with the source. See doc/guide/bind10-guide.txt
(or bind10-guide.html) for installation instructions. The
documentation is also available via the BIND 10 website at
......
......@@ -2,7 +2,7 @@
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.59])
AC_INIT(bind10, 20130221, bind10-dev@isc.org)
AC_INIT(bind10, 20130510, bind10-dev@isc.org)
AC_CONFIG_SRCDIR(README)
# serial-tests is not available in automake version before 1.13. In
# automake 1.13 and higher, AM_PROG_INSTALL is undefined, so we'll check
......@@ -323,9 +323,9 @@ if test -x ${PYTHON}-config; then
# so we only go through the flag if it's contained; also, protecting
# the output with [] seems necessary for environment to avoid getting
# an empty output accidentally.
python_config_ldflags=[`${PYTHON}-config --ldflags | sed -ne 's/\([ \t]*-L\)[ ]*\([^ \t]*[ \t]*\)/\1\2/pg'`]
python_config_ldflags=[`${PYTHON}-config --ldflags | ${SED} -ne 's/\([ \t]*-L\)[ ]*\([^ \t]*[ \t]*\)/\1\2/gp'`]
for flag in $python_config_ldflags; do
flag=`echo $flag | sed -ne 's/^\(\-L.*\)$/\1/p'`
flag=`echo $flag | ${SED} -ne 's/^\(\-L.*\)$/\1/p'`
if test "X${flag}" != X; then
PYTHON_LDFLAGS="$PYTHON_LDFLAGS ${flag}"
fi
......@@ -351,7 +351,7 @@ fi
if test "x$ISC_RPATH_FLAG" != "x"; then
python_rpath=
for flag in ${PYTHON_LDFLAGS}; do
python_rpath="${python_rpath} `echo $flag | sed -ne "s/^\(\-L\)/${ISC_RPATH_FLAG}/p"`"
python_rpath="${python_rpath} `echo $flag | ${SED} -ne "s/^\(\-L\)/${ISC_RPATH_FLAG}/p"`"
done
PYTHON_LDFLAGS="${PYTHON_LDFLAGS} ${python_rpath}"
fi
......@@ -388,8 +388,6 @@ In this case we will continue, but naming of python processes will not work.])
fi
fi
# TODO: check for _sqlite3.py module
# (g++ only check)
# Python 3.2 has an unused parameter in one of its headers. This
# has been reported, but not fixed as of yet, so we check if we need
......@@ -536,7 +534,7 @@ if test "$lcov" != "no"; then
AC_MSG_ERROR([Cannot find lcov.])
fi
# is genhtml always in the same directory?
GENHTML=`echo "$LCOV" | sed s/lcov$/genhtml/`
GENHTML=`echo "$LCOV" | ${SED} s/lcov$/genhtml/`
if test ! -x $GENHTML; then
AC_MSG_ERROR([genhtml not found, needed for lcov])
fi
......@@ -712,15 +710,15 @@ fi
BOTAN_LDFLAGS=
BOTAN_NEWLIBS=
for flag in ${BOTAN_LIBS}; do
BOTAN_LDFLAGS="${BOTAN_LDFLAGS} `echo $flag | sed -ne '/^\(\-L\)/p'`"
BOTAN_LIBS="${BOTAN_LIBS} `echo $flag | sed -ne '/^\(\-l\)/p'`"
BOTAN_LDFLAGS="${BOTAN_LDFLAGS} `echo $flag | ${SED} -ne '/^\(\-L\)/p'`"
BOTAN_LIBS="${BOTAN_LIBS} `echo $flag | ${SED} -ne '/^\(\-l\)/p'`"
done
# See python_rpath for some info on why we do this
if test "x$ISC_RPATH_FLAG" != "x"; then
BOTAN_RPATH=
for flag in ${BOTAN_LIBS}; do
BOTAN_RPATH="${BOTAN_RPATH} `echo $flag | sed -ne "s/^\(\-L\)/${ISC_RPATH_FLAG}/p"`"
BOTAN_RPATH="${BOTAN_RPATH} `echo $flag | ${SED} -ne "s/^\(\-L\)/${ISC_RPATH_FLAG}/p"`"
done
AC_SUBST(BOTAN_RPATH)
......@@ -890,9 +888,12 @@ AC_ARG_WITH(shared-memory,
[Build with Boost shared memory support; for large scale authoritative DNS servers]),
[use_shared_memory=$withval])
if test X$use_shared_memory = Xyes -a "$BOOST_MAPPED_FILE_WOULDFAIL" = "yes"; then
AC_MSG_ERROR([Boost shared memory does not compile on this system. If you don't need it (most normal users won't) build without it; using a different compiler or a different version of Boost may also help.])
AC_MSG_ERROR([Boost shared memory does not compile on this system. If you don't need it (most normal users won't) build without it by rerunning this script with --without-shared-memory; using a different compiler or a different version of Boost may also help.])
fi
AM_CONDITIONAL([USE_SHARED_MEMORY], [test x$use_shared_memory = xyes])
if test "x$use_shared_memory" = "xyes"; then
AC_DEFINE(USE_SHARED_MEMORY, 1, [Define to 1 if shared memory support is enabled])
fi
AC_SUBST(BOOST_MAPPED_FILE_CXXFLAG)
# Add some default CPP flags needed for Boost, identified by the AX macro.
......@@ -1043,12 +1044,16 @@ AC_SUBST(GTEST_LDFLAGS)
AC_SUBST(GTEST_LDADD)
AC_SUBST(GTEST_SOURCE)
dnl check for pkg-config itself so we don't try the m4 macro without pkg-config
dnl check for pkg-config itself
AC_CHECK_PROG(HAVE_PKG_CONFIG, pkg-config, yes, no)
if test "x$HAVE_PKG_CONFIG" = "xno" ; then
AC_MSG_ERROR(Please install pkg-config)
fi
PKG_CHECK_MODULES(SQLITE, sqlite3 >= 3.3.9, enable_features="$enable_features SQLite3")
AX_SQLITE3_FOR_BIND10
if test "x$have_sqlite" = "xyes" ; then
enable_features="$enable_features SQLite3"
fi
#
# ASIO: we extensively use it as the C++ event management module.
......@@ -1201,6 +1206,7 @@ AC_CONFIG_FILES([Makefile
src/bin/dhcp4/tests/Makefile
src/bin/resolver/Makefile
src/bin/resolver/tests/Makefile
src/bin/resolver/bench/Makefile
src/bin/sysinfo/Makefile
src/bin/sockcreator/Makefile
src/bin/sockcreator/tests/Makefile
......@@ -1316,13 +1322,13 @@ AC_CONFIG_FILES([Makefile
src/lib/statistics/Makefile
src/lib/statistics/tests/Makefile
tests/Makefile
tests/system/Makefile
tests/tools/Makefile
tests/tools/badpacket/Makefile
tests/tools/badpacket/tests/Makefile
tests/tools/perfdhcp/Makefile
tests/tools/perfdhcp/tests/Makefile
tests/tools/perfdhcp/tests/testdata/Makefile
m4macros/Makefile
dns++.pc
])
AC_OUTPUT([doc/version.ent
......@@ -1400,23 +1406,6 @@ AC_OUTPUT([doc/version.ent
src/lib/util/python/gen_wiredata.py
src/lib/server_common/tests/data_path.h
tests/lettuce/setup_intree_bind10.sh
tests/system/conf.sh
tests/system/run.sh
tests/system/glue/setup.sh
tests/system/glue/nsx1/b10-config.db
tests/system/bindctl/nsx1/b10-config.db.template
tests/system/ixfr/db.example.n0
tests/system/ixfr/db.example.n2
tests/system/ixfr/db.example.n2.refresh
tests/system/ixfr/db.example.n4
tests/system/ixfr/db.example.n6
tests/system/ixfr/ixfr_init.sh
tests/system/ixfr/b10-config.db
tests/system/ixfr/common_tests.sh
tests/system/ixfr/in-1/setup.sh
tests/system/ixfr/in-2/setup.sh
tests/system/ixfr/in-3/setup.sh
tests/system/ixfr/in-4/setup.sh
], [
chmod +x src/bin/cmdctl/run_b10-cmdctl.sh
chmod +x src/bin/xfrin/run_b10-xfrin.sh
......@@ -1447,14 +1436,6 @@ AC_OUTPUT([doc/version.ent
chmod +x src/lib/util/python/mkpywrapper.py
chmod +x src/lib/util/python/gen_wiredata.py
chmod +x src/lib/python/isc/log/tests/log_console.py
chmod +x tests/system/conf.sh
chmod +x tests/system/run.sh
chmod +x tests/system/ixfr/ixfr_init.sh
chmod +x tests/system/ixfr/common_tests.sh
chmod +x tests/system/ixfr/in-1/setup.sh
chmod +x tests/system/ixfr/in-2/setup.sh
chmod +x tests/system/ixfr/in-3/setup.sh
chmod +x tests/system/ixfr/in-4/setup.sh
])
AC_OUTPUT
......
The IPC protocol
================
While the cc-protocol.txt describes the low-level primitives, here we
describe how the whole IPC should work and how to use it.
Definitions
-----------
system::
The system that moves data between the users and does bookkeeping.
In our current implementation, it is implemented as the MsgQ daemon,
which the users connect to and it routes the data.
user::
Usually a process; generally an entity that wants to communicate
with the other users.
session::
Session is the interface by which the user communicates with the
system. Single user may have multiple sessions, a session belongs to
single user.
message::
A data blob sent by one user. The recipient might be the system
itself, other session or set of sessions (called group, see below,
it is possibly empty). Message is either a response or an original
message (TODO: Better name?).
group::
A named set of sessions. Conceptually, all the possible groups
exist, there's no explicit creation and deletion of groups.
session id::
Unique identifier of a session. It is not reused for the whole
lifetime of the system. Historically called `lname` in the code.
undelivery signal::
While sending an original message, a client may request an
undelivery signal. If the recipient specification yields no
sessions to deliver the message to, the system informs user about
the situation.
sequence number::
Each message sent through the system carries a sequence number. The
number should be unique per sender. It can be used to pair a
response to the original message, since the response specifies which
sequence number had the message it response to. Even responses and
messages not expecting answer have their sequence number, but it is
generally unused.
non-blocking operation::
Operation that will complete without waiting for anything.
fast operation::
Operation that may wait for other process, but only for a very short
time. Generally, this includes communication between the user and
system, but not between two clients. It can be expected to be fast
enough to use this inside an interactive session, but may be too
heavy in the middle of query processing, for example. Every
non-blocking operation is considered fast.
The session
-----------
The session interface allows for several operations interacting with
the system. In the code, it is represented by a class.
Possible operations include:
Opening a session::
The session is created and connects to the system. This operation is
fast. The session receives session id from the system.
Group management::
A user may subscribe (become member) of a group, or unsubscribe from
a group. These are fast operations.
Send::
A user may send a message, addressed to the system, or other
session(s). This operation is expected to be non-blocking
(current implementation is based on assumption of how OS handles the
sends, which may need to be revisited if it turns out to be false).
Receive synchronously::
User may wait for an incoming message in blocking mode. It is
possible to specify the kind of message to wait for, either original
message or response to a message. This interface has a timeout.
Receive asynchronously::
Similar to previous, but non-blocking. It terminates immediately.
The user provides a callback that is invoked when the requested
message arrives.
Terminate::
A session may be terminated. No more messages are sent or received
over it, the session is automatically unsubscribed from all the
groups. This operation is non-blocking. A session is terminated
automatically if the user exits.
Assumptions
-----------
We assume reliability and order of delivery. Messages sent from user A
to B are all delivered unchanged in original order as long as B
exists.
All above operations are expected to always succeed. If there's an
error reported, it should be considered fatal and user should
exit. In case a user still wants to continue, the session must be
considered terminated and a new one must be created. Care must be
taken not to use any information obtained from the previous session,
since the state in other users and the system may have changed during
the reconnect.
Addressing
----------
Addressing happens in three ways:
By group name::
The message is routed to all the sessions subscribed to this group.
It is legal to address an empty group; such message is then
delivered to no sessions.
By session ID::
The message is sent to the single session, if it is still alive.
By an alias::
A session may have any number of aliases - well known names. Only
single session may hold given alias (but it is not yet enforced by
the system). The message is delivered to the one session owning the
alias, if any. Internally, the aliases are implemented as groups
with single subscribed session, so it is the same as the first
option on the protocol level, but semantically it is different.
The system
----------
The system performs these goals:
* Maintains the open sessions and allows creating new ones.
* Keeps information about groups and which sessions are subscribed to
which group.
* Routes the messages between users.
Also, the system itself is a user of the system. It can be reached by
the alias `Msgq` and provides following high-level services (see
below):
Notifications about sessions::
When a session is opened to the system or when a session is
terminated, a notification is sent to interested users. The
notification contains the session ID of the session in question.
The termination notification is probably more useful (if a user
communicated with a given session before, it might be interested it
is no longer available), the opening notification is provided mostly
for completeness.
Notifications about group subscriptions::
When a session subscribes to a group or unsubscribes from a group, a
notification is sent to interested users. The notification contains
both the session ID of the session subscribing/unsubscribing and
name of the group. This includes notifications about aliases (since
aliases are groups internally).
Commands to list sessions::
There's a command to list session IDs of all currently opened sessions
and a command to list session IDs of all sessions subscribed to a
given group. Note that using these lists might need some care, as
the information might be outdated at the time it is delivered to the
user.
User shows interest in notifications about sessions and group
subscriptions by subscribing to a group with well-known name (as with
any notification).
Note that due to implementation details, the `Msgq` alias is not yet
available during early stage of the bootstrap of bind10 system. This
means some very core services can't rely on the above services of the
system. The alias is guaranteed to be working before the first
non-core module is started.
Higher-level services
---------------------
While the system is able to send any kind of data, the payload sent by
users in bind10 is structured data encoded as JSON. The messages sent
are of three general types:
Command::
A message sent to single destination, with the undeliverable
signal turned on and expecting an answer. This is a request
to perform some operation on the recipient (it can have side effects
or not). The command is identified by a name and it can have
parameters. A command with the same name may behave differently (or
have different parameters) on different receiving users.
Reply::
An answer to the `Command`. It is sent directly to the session where
the command originated from, does not expect further answer and the
undeliverable notification is not set. It either confirms the
command was run successfully and contains an optional result, or
notifies the sender of failure to run the command. Success and
failure differ only in the payload sent through the system, not in
the way it is sent. The undeliverable signal is failure
reply sent by the system on behalf of the missing recipient.
Notification::
A message sent to any number of destinations (eg. sent to a group),
not expecting an answer. It notifies other users about an event or
change of state.
Details of the higher-level
---------------------------
While there are libraries implementing the communication in convenient
way, it is useful to know what happens inside.
The notifications are probably the simplest. Users interested in
receiving notifications of some family subscribe to corresponding
group. Then, a client sends a message to the group. For example, if
clients `receiver-A` and `receiver-B` want to receive notifications
about changes to zone data, they'd subscribe to the
`Notifications/ZoneUpdates` group. Then, other client (let's say
`XfrIn`, with session ID `s12345`) would send something like:
s12345 -> Notifications/ZoneUpdates
{"notification": ["zone-update", {
"class": "IN",
"origin": "example.org.",
"serial": 123456
}]}
Both receivers would receive the message and know that the
`example.org` zone is now at version 123456. Note that multiple users
may produce the same kind of notification. Also, single group may be
used to send multiple notification names (but they should be related;
in our example, the `Notifications/ZoneUpdates` could be used for
`zone-update`, `zone-available` and `zone-unavailable` notifications
for change in zone data, configuration of new zone in the system and
removal of a zone from configuration).