vSomeIP 2.5.02.5.0

1 files changed, 1245 insertions, 0 deletions

diff --git a/documentation/vsomeipUserGuide b/documentation/vsomeipUserGuide
new file mode 100644
index 0000000..491a136
--- /dev/null
+++ b/documentation/vsomeipUserGuide
@@ -0,0 +1,1245 @@
+vsomeip
+=======
+// This enables a nice TOC as a sidebar
+:toc2:
+// Show all headings in TOC
+:toclevels: 4
+// Show icons if e.g. TIP: or IMPORTANT is used
+:icons:
+// Set the directory where the default icons can be found
+:iconsdir: {asciidoc-confdir}/{iconsdir}
+// number all headings
+:numbered:
+// this embeds images (e.g. the icons for TIP: $TEXT) into the html file
+:data-uri:
+
+Copyright
++++++++++
+Copyright (C) 2015-2016, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+
+License
++++++++
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+Version
++++++++
+// set the version to the one we get from cmake
+// or pass it via -a version=$VSOMEIP_VERSION to asciidoc
+This documentation was generated for version {version} of vsomeip.
+
+vsomeip Overview
+----------------
+The vsomeip stack implements the http://some-ip.com/[Scalable service-Oriented
+MiddlewarE over IP (SOME/IP)] protocol. The stack consists out of:
+
+* a shared library for SOME/IP (`libvsomeip.so`)
+* a second shared library for SOME/IP's service discovery (`libvsomeip-sd.so`)
+  which is loaded during runtime if the service discovery is enabled.
+
+Build Instructions
+------------------
+Dependencies
+~~~~~~~~~~~~
+* A C++11 enabled compiler like gcc >= 4.8 is needed.
+* vsomeip uses cmake as buildsystem.
+* vsomeip uses Boost >= 1.55:
+** Ubuntu 14.04:
+*** `sudo apt-get install libboost-system1.55-dev libboost-thread1.55-dev
+    libboost-log1.55-dev`
+** Ubuntu 12.04: a PPA is necessary to use version 1.54 of Boost:
+*** URL: https://launchpad.net/~boost-latest/+archive/ubuntu/ppa
+*** `sudo add-apt-repository ppa:boost-latest/ppa`
+*** `sudo apt-get install libboost-system1.55-dev libboost-thread1.55-dev
+    libboost-log1.55-dev`
+* For the tests Google's test framework
+  https://code.google.com/p/googletest/[gtest] in version 1.7.0 is needed
+** URL: https://googletest.googlecode.com/files/gtest-1.7.0.zip[direct link,
+   version 1.7.0]
+* To build the documentation asciidoc, source-highlight, doxygen and graphviz is needed:
+** `sudo apt-get install asciidoc source-highlight doxygen graphviz`
+
+Compilation
+~~~~~~~~~~~
+anchor:Compilation[]
+For compilation call:
+[source, bash]
+----
+mkdir build
+cd build
+cmake ..
+make
+----
+
+To specify a installation directory (like `--prefix=` if you're used to
+autotools) call cmake like:
+[source, bash]
+----
+cmake -DCMAKE_INSTALL_PREFIX:PATH=$YOUR_PATH ..
+make
+make install
+----
+
+Compilation with predefined unicast and/or diagnosis address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To predefine the unicast address, call cmake like:
+[source,bash]
+----
+cmake -DUNICAST_ADDRESS=<YOUR IP ADDRESS> ..
+----
+
+To predefine the diagnosis address, call cmake like:
+[source,bash]
+----
+cmake -DDIAGNOSIS_ADDRESS=<YOUR DIAGNOSIS ADDRESS> ..
+----
+The diagnosis address is a single byte value.
+
+Compilation with signal handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To compile vsomeip with signal handling (SIGINT/SIGTERM) enabled,
+call cmake like:
+[source,bash]
+----
+cmake -DENABLE_SIGNAL_HANDLING=1 ..
+----
+In the default setting, the application has to take care of shutting
+down vsomeip in case these signals are received.
+
+Compilation of examples
+^^^^^^^^^^^^^^^^^^^^^^^
+For compilation of the examples call:
+[source, bash]
+----
+mkdir build
+cd build
+cmake ..
+make examples
+----
+
+Compilation of tests
+^^^^^^^^^^^^^^^^^^^^
+To compile the tests, first unzip gtest to location of your desire.
+Some of the tests require a second node on the same network. There are two cmake
+variables which are used to automatically adapt the json files to the used
+network setup:
+
+* `TEST_IP_MASTER`: The IP address of the interface which will act as test
+  master.
+* `TEST_IP_SLAVE`: The IP address of the interface of the second node which will
+  act as test slave.
+
+If one of this variables isn't specified, only the tests using local
+communication exclusively will be runnable.
+
+Additionally the unit tests require enabled signal handling which can be enabled
+via the `ENABLE_SIGNAL_HANDLING` cmake variable.
+
+Example, compilation of tests:
+[source, bash]
+----
+mkdir build
+cd build
+export GTEST_ROOT=$PATH_TO_GTEST/gtest-1.7.0/
+cmake -DENABLE_SIGNAL_HANDLING=1 -DTEST_IP_MASTER=10.0.3.1 -DTEST_IP_SLAVE=10.0.3.125 ..
+make check
+----
+
+Additional make targets for the tests:
+
+* Call `make build_tests` to only compile the tests
+* Call `ctest` in the build directory to execute the tests without a verbose
+  output
+* To run single tests call `ctest --verbose --tests-regex $TESTNAME` short
+  form: `ctest -V -R $TESTNAME`
+* To list all available tests run `ctest -N`.
+* For further information about the tests please have a look at the
+  `readme.txt` in the `test` subdirectory.
+
+For development purposes two cmake variables exist which control if the
+json files and test scripts are copied (default) or symlinked into the build
+directory. These settings are ignored on Windows.
+
+* `TEST_SYMLINK_CONFIG_FILES`: Controls if the json and scripts needed
+  to run the tests are copied or symlinked into the build directory. (Default:
+  OFF, ignored on Windows)
+* `TEST_SYMLINK_CONFIG_FILES_RELATIVE`: Controls if the json and scripts needed
+  to run the tests are symlinked relatively into the build directory.
+  (Default: OFF, ignored on Windows)
+
+Example cmake call:
+[source, bash]
+----
+cmake  -DTEST_SYMLINK_CONFIG_FILES=ON -DTEST_SYMLINK_CONFIG_FILES_RELATIVE=ON ..
+----
+
+For compilation of only a subset of tests (for a quick
+functionality check) the cmake variable `TESTS_BAT` has
+to be set:
+
+Example cmake call:
+[source, bash]
+----
+cmake  -DTESTS_BAT=ON ..
+----
+
+Compilation of vsomeip_ctrl
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For compilation of the <<vsomeip_ctrl>> utility call:
+[source, bash]
+----
+mkdir build
+cd build
+cmake ..
+make vsomeip_ctrl
+----
+
+Generating the documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To generate the documentation call cmake as described in <<Compilation>> and
+then call `make doc`.
+This will generate:
+
+* The README file in html: `$BUILDDIR/documentation/README.html`
+* A doxygen documentation in `$BUILDDIR/documentation/html/index.html`
+
+Starting vsomeip Applications / Used environment variables
+----------------------------------------------------------
+On startup the following environment variables are read out:
+
+* `VSOMEIP_APPLICATION_NAME`: This environment variable is used to specify the
+  name of the application. This name is later used to map a client id to the
+  application in the configuration file. It is independent from the
+  application's binary name.
+* `VSOMEIP_CONFIGURATION`: vsomeip uses the default configuration file `/etc/vsomeip.json`
+   and/or the default configuration folder `/etc/vsomeip`. This can be overridden by a
+   local configuration file `./vsomeip.json` and/or a local configuration folder `./vsomeip`.
+   If `VSOMEIP_CONFIGURATION` is set to a valid file or directory path, this is used instead
+   of the standard configuration (thus neither default nor local file/folder will be parsed).
+* `VSOMEIP_MANDATORY_CONFIGURATION_FILES`: vsomeip allows to specify mandatory configuration
+   files to speed-up application startup. While mandatory configuration files are read by all
+   applications, all other configuration files are only read by the application that is 
+   responsible for connections to external devices. If this configuration variable is not set,
+   the default mandatory files vsomeip_std.json, vsomeip_app.json and vsomeip_plc.json are used.
+
+NOTE: If the file/folder that is configured by `VSOMEIP_CONFIGURATION` does _not_ exist,
+the default configuration locations will be used.
+
+NOTE: vsomeip will parse and use the configuration from all files in a configuration folder
+but will _not_ consider directories within the configuration folder.
+
+In the following example the application `my_vsomeip_application` is started.
+The settings are read from the file `my_settings.json` in the current working
+directory. The client id for the application can be found under the name
+`my_vsomeip_client` in the configuration file.
+
+[source, bash]
+----
+#!/bin/bash
+export VSOMEIP_APPLICATION_NAME=my_vsomeip_client
+export VSOMEIP_CONFIGURATION=my_settings.json
+./my_vsomeip_application
+----
+
+Configuration File Structure
+----------------------------
+The configuration files for vsomeip are http://www.json.org/[JSON]-Files and are
+composed out of multiple key value pairs and arrays.
+
+[quote, , json.org]
+____
+* An object is an unordered set of name/value pairs. An object begins with `{
+(left brace)` and ends with `} (right brace)`. Each name is followed by `:
+(colon)` and the name/value pairs are separated by `, (comma)`.
+
+* An array is an ordered collection of values. An array begins with `[ (left
+bracket)` and ends with `] (right bracket)`. Values are separated by `,
+(comma)`.
+
+* A value can be a _string_ in double quotes, or a _number_, or `true` or `false`
+or `null`, or an _object_ or an _array_. These structures can be nested.
+____
+
+Configuration file element explanation:
+
+
+* 'unicast'
++
+The IP address of the host system.
++
+* 'netmask'
++
+The netmask to specify the subnet of the host system.
++
+* 'diagnosis'
++
+The diagnosis address (byte) that will be used to build client identifiers.
++
+//Logging
+* 'logging'
++
+** 'level'
++
+Specifies the log level (valid values: _trace_, _debug_, _info_, _warning_,
+_error_, _fatal_).
++
+** 'console'
++
+Specifies whether logging via console is enabled (valid values: _true, false_).
++
+** 'file'
++
+*** 'enable'
++
+Specifies whether a log file should be created (valid values: _true, false_).
++
+*** 'path'
++
+The absolute path of the log file.
++
+** 'dlt'
++
+Specifies whether Diagnostic Log and Trace (DLT) is enabled (valid values:
+_true, false_).
++
+//Tracing
+* anchor:config-tracing[]'tracing' (optional)
++
+** 'enable'
++
+Specifies whether the tracing of the SOME/IP messages is enabled 
+(valid values: _true, false_). Default value is _false_.
+If tracing is enabled, the messages will be forwarded to DLT by 
+the <<traceconnector, Trace Connector>>
++
+** 'sd_enable'
++
+Specifies whether the tracing of the SOME/IP service discovery messages is 
+enabled (valid values: _true, false_). Default value is _false_.
++
+** 'channels (array)' (optional)
++
+Contains the channels to DLT.
++
+NOTE: You can set up multiple channels to DLT over that you can forward the
+messages.
++
+*** 'name'
++
+The name of the channel.
++
+*** 'id'
++
+The id of the channel. 
++
+** 'filters (array)' (optional)
++
+Contains the filters that are applied on the messages.
++
+NOTE: You can apply filters respectively filter rules on the messages with 
+specific criterias and expressions. So only the filtered messages are forwarded 
+to DLT.
++
+*** 'channel' (optional)
++
+The id of the channel over that the filtered messages are forwarded to DLT. If
+no channel is specified the default channel is used.
++
+IMPORTANT: If multiple filters are used, the channel MUST always be 
+specified and accordingly defined! Each filter needs its own channel!
++
+*** 'services (array)' (optional)
++
+Contains the service ids. The messages that relates to the specified services will be filtered.
++
+*** 'methods (array)' (optional)
++
+Contains the method ids. The messages that relates to the specified methods will be filtered.
++
+*** 'clients (array)' (optional)
++
+Contains the client ids. The messages that relates to the specified clients will
+be filtered.
++
+//Applications
+* 'applications (array)'
++
+Contains the applications of the host system that use this config file.
++
+** 'name'
++
+The name of the application.
++
+** 'id'
++
+The id of the application.
++
+** 'max_dispatchers'
++
+The maximum number of threads that shall be used to execute the application callbacks.
++
+** 'max_dispatch_time'
++
+The maximum time that an application callback may consume before the callback is
+considered to be blocked (and an additional thread is used to execute pending
+callbacks if max_dispatchers is configured greater than 0).
++
+* `services` (array)
++
+Contains the services of the service provider.
+
+** `service`
++
+The id of the service.
+
+** `instance`
++
+The id of the service instance.
+
+** `protocol` (optional)
++
+The protocol that is used to implement the service instance. The default setting
+is _someip_. If a different setting is provided, vsomeip does not open the specified
+port (server side) or does not connect to the specified port (client side). Thus,
+this option can be used to let the service discovery announce a service that is
+externally implemented. 
+
+** `unicast` (optional)
++
+The unicast that hosts the service instance.
++
+NOTE: The unicast address is needed if external service instances shall be used,
+but service discovery is disabled. In this case, the provided unicast address
+is used to access the service instance. 
+
+** `reliable`
++
+Specifies that the communication with the service is reliable respectively the
+TCP protocol is used for communication.
+
+*** `port`
++
+The port of the TCP endpoint.
+
+*** `enable-magic-cookies`
++
+Specifies whether magic cookies are enabled (valid values: _true_, _false_).
+
+** `unreliable`
++
+Specifies that the communication with the service is unreliable respectively the
+UDP protocol is used for communication (valid values: the _port_ of the UDP
+endpoint).
+
+** `events` (array)
++
+Contains the events of the service.
+
+*** `event`
++
+The id of the event.
+
+*** `is_field`
++
+Specifies whether the event is of type field.
++
+NOTE: A field is a combination of getter, setter and notification event. It
+contains at least a getter, a setter, or a notifier. The notifier sends an event
+message that transports the current value of a field on change.
+
+*** `is_reliable`
++
+Specifies whether the communication is reliable respectively whether the event
+is sent with the TCP protocol (valid values: _true_,_false_).
++
+If the value is _false_ the UDP protocol will be used.
+
+** `eventgroups` (array)
++
+Events can be grouped together into on event group. For a client it is thus
+possible to subscribe for an event group and to receive the appropriate events
+within the group.
+
+*** `eventgroup`
++
+The id of the event group.
+
+*** `events` (array)
++
+Contains the ids of the appropriate events.
+
+*** `multicast`
++
+Specifies the multicast that is used to publish the eventgroup.
+
+**** `address`
++
+The multicast address.
+
+**** `port`
++
+The multicast port.
+
+*** `threshold`
++
+Specifies when to use multicast and when to use unicast to send a notification event.
+Must be set to a non-negative number. If it is set to zero, all events of the eventgroup
+will be sent by unicast. Otherwise, the events will be sent by unicast as long as the
+number of subscribers is lower than the threshold and by multicast if the number
+of subscribers is greater or equal. This means, a threshold of 1 will lead to all events
+being sent by multicast. The default value is _0_.  
+
+* `clients` (array)
++
+The client-side ports that shall be used to connect to a specific service.
+For each service, an array of ports to be used for reliable / unreliable
+communication can be specified. vsomeip will take the first free port of
+the list. If no free port can be found, the connection will fail. If 
+vsomeip is asked to connect to a service instance without specified port(s),
+the port will be selected by the system. This implies that the user has
+to ensure that the ports configured here do not overlap with the ports
+automatically selected by the IP stack.
+
+** `service`
+** `instance`
++
+Together they specify the service instance the port configuration shall be applied to.
+
+** `reliable` (array)
++
+The list of client ports to be used for reliable (TCP) communication to the given
+service instance. 
+
+** `unreliable` (array)
++
+The list of client ports to be used for unreliable (UDP) communication to the given
+service instance. 
+
+* `payload-sizes` (array)
++
+Array to specify the maximum allowed payload sizes per IP and port. If not
+specified, or a smaller value than the default values is specified, the default
+values are used. The settings in this array only affect communication over TCP
+and local communication over UNIX domain sockets.
+
+** `unicast`
++
+On client side: the IP of the remote service to which the oversized messages
+should be sent.
+On service side: the IP of the offered service which should receive the
+oversized messages and is allowed to respond with oversized messages.
+If client and service only communicate locally, any IP can be entered here as
+for local communication only the maximum specified payload size is relevant.
+
+** `ports` (array)
++
+Array which holds pairs of port and payload-size statements.
+
+*** `port`
++
+On client side: the port of the remote service to which the oversized messages
+should be sent.
+On service side: the port of the offered service which should receive the
+oversized messages and is allowed to respond with oversized messages.
+If client and service only communicate locally, any port number can be entered.
+
+*** `max-payload-size`
++
+On client side: the maximum payload size in bytes of a message sent to the
+remote service hosted on beforehand specified IP and port.
+On service side: the maximum payload size in bytes of messages received by the
+service offered on previously specified IP and port. If multiple services are
+hosted on the same port all of them are allowed to receive oversized messages
+and send oversized responses.
+
+* `internal_services` (optional array)
++
+Specifies service/instance ranges for pure internal service-instances.
+This information is used by vSomeIP to avoid sending Find-Service messages
+via the Service-Discovery when a client is requesting a not available service-
+instance. Its can either be done on service/instance level or on service level
+only which then includes all instance from 0x0000-0xffff.
+
+** `first`
++
+The lowest entry of the internal service range.
+
+*** `service`
++
+The lowest Service-ID in hex of the internal service range.
+
+*** `instance` (optional)
++
+The lowest Instance-ID in hex of a internal service-instance range.
+If not specified the lowest Instance-ID is 0x0000.
+
+** `last`
++
+The highest entry of the internal service range.
+
+*** `service`
++
+The highest Service-ID in hex of a internal service range.
+
+*** `instance` (optional)
++
+The highest Instance-ID in hex of a internal service-instance range.
+If not specified the highest Instance-ID is 0xFFFF.
+
+* `routing`
++
+The name of the application that is responsible for the routing.
+
+* `service-discovery`
++
+Contains settings related to the Service Discovery of the host application.
+
+** `enable`
++
+Specifies whether the Service Discovery is enabled (valid values: _true_,
+_false_). The default value is _true_.
+
+** `multicast`
++
+The multicast address which the messages of the Service Discovery will be sent
+to. The default value is _224.0.0.1_.
+
+** `port`
++
+The port of the Service Discovery. The default setting is _30490_.
+
+** `protocol`
++
+The protocol that is used for sending the Service Discovery messages (valid
+values: _tcp_, _udp_). The default setting is _udp_.
+
+** `initial_delay_min`
++
+Minimum delay before first offer message.
+
+** `initial_delay_max`
++
+Maximum delay before first offer message.
+
+** `repetitions_base_delay`
++
+Base delay sending offer messages within the repetition phase.
+ 
+** `repetitions_max`
++
+Maximum number of repetitions for provided services within the 
+repetition phase.
+ 
+** `ttl`
++
+Lifetime of entries for provided services as well as consumed services and eventgroups.
+
+** `cyclic_offer_delay`
++
+Cycle of the OfferService messages in the main phase.
+
+** `request_response_delay`
++
+Minimum delay of a unicast message to a multicast message for
+provided services and eventgroups.
++
+
+** `offer_debounce_time`
++
+Time which the stack collects new service offers before they enter the
+repetition phase. This can be used to reduce the number of
+sent messages during startup. The default setting is _500ms_.
++
+//Watchdog
+* anchor:config-watchdog[]'watchdog' (optional)
++
+The Watchdog sends periodically pings to all known local clients.
+If a client isn't responding within a configurred time/amount of pongs
+the watchdog deregisters this application/client.
+If not configured the watchdog isn't activated.
++
+** 'enable'
++
+Specifies whether the watchdog is enabled or disabled.
+(valid values: _true, false_), (default is _false_).
++
+** 'timeout'
++
+Specifies the timeout in ms the watchdog gets activated if a ping
+isn't answered with a pong by a local client within that time.
+(valid values: _2 - 2^32_), (default is _5000_ ms).
++
+** 'allowed_missing_pongs'
++
+Specifies the amount of allowed missing pongs.
+(valid values: _1 - 2^32_), (default is _3_ pongs).
++
+//CAPI-Selective Broadcasts support
+* anchor:config-supports_selective_broadcasts[]'supports_selective_broadcasts' (optional)
++
+This nodes allow to add a list of IP addresses on which CAPI-Selective-Broadcasts feature is supported.
+If not specified the feature can't be used and the subscription behavior of the stack is same as with
+normal events.
++
+** 'address'
++
+Specifies an IP-Address (in IPv4 or IPv6 notation) on which the "selective"-feature is supported.
+Multiple addresses can be configuered.
+
+Security
+--------
+vSomeIP has a security implementation based on UNIX credentials.
+If activated every local connection is authenticated during connect using the standard UNIX credential passing mechanism.
+During authentification a client transfers its client identifier together with its credentials (UID / GID) to the server which is then matched against the configuration.
+If received credentials don't match the policy the socket will be immediately closed by the server and an message is logged.
+If accepted the client identifier is bound to the receiving socket and can therefore be used to do further security checks on incoming messages (vSomeIP messages as well as internal commands).
+
+In general clients can be configured to be allowed/denied to request (means communicate with) and offer different service instances.
+Every incoming vSomeIP message (request/response/notifcation) as well as offer service requests or local subscriptions are then checked against the policy.
+If an incoming vSomeIP message or another operation (e.g. offer/subscribe) violates the configured policies it is skipped and a message is logged.
+
+Furthermore if an application receives a routing table (information about other clients/services in the system) it must be received from the authenticated routing manager which means the routing manager must be a configured application if security is active.
+This should avoid malicious applications faking the routing manager and therfore could wrongly inform other clients about services running on the system.
+
+Credential passing is only possible via Unix-Domain-Sockets and therefore only available for local communication.
+However if security is activated method calls from remote clients to local services are checked as well which means remote clients needs to be explicitly allowed.
+Such a policy looks same in case for local clients except the _credentials_ tag can be skipped.
+
+It follows the available configuration switches for the security feature including its functional behavior: 
+
+// Security
+* anchor:config-policy[]'security' (optional)
++
+If specified the credential passing mechanism is activated. However no credential or security checks are done as long as _check_credentials_ isn't set to _true_.
+
+** 'check_credentials (optional)'
++
+Specifies whether security checks are active or not. This includes credentials checks on connect as well as all policies checks configured in follow.
+(valid values: _true, false_), (default is _false_).
+
+** 'policies' (array)
++
+Specifies the security policies. Each policy at least needs to specify _client_ and _allow_ / _deny_.
+
+*** 'client'
++
+Specifies a client for which a security policy will be applied (valid value: A valid client identifier in hex: e.g. _0x1234_).
+It is also possible to specify a client identifier range to easily apply a policy to a set of clients.
+A usecase is e.g. to allow a set of remote clients communicate with local services offered remote.
+
+**** 'first'
++
+Specifies the first client of a range (first is included).
+(valid value: A valid client identifier in hex: e.g. _0x1234_)
+
+**** 'last'
++
+Specifies the last client id of a range (last is included).
+(valid value: A valid client identifier in hex: e.g. _0x1234_)
+
+*** 'credentials' (optional)
++
+Specifies the credentials of the above client(s).
+If _check_credentials_ is set to _true_ the credentials for the above client(s) (if they running locally) needs to be specified correctly to ensure local socket authentification can succeed.
+This entry is optional due to the fact that remote clients needs to be configured as well to allow to communicate with local services as already mentioned above.
+For remote clients this entry should be skipped. 
+
+**** 'uid'
++
+Specifies the LINUX user id of the above client(s) as decimal number.
+
+**** 'gid'
++
+Specifies the LINUX group id of the above client(s) as decimal number.
+
+*** 'allow/deny'
++
+This tag specifies either _allow_ or _deny_ depending on white- or blacklisting is needed. Specifing _allow_ and _deny_ entries in one policy is therefore not allowed.
+With _allow_ a whitelisting of what is allowed can be done which means an empty _allow_ tag implies everything is denied.
+With _deny_ a blacklisting of what is allowed can be done which means an empty _deny_ tag implies everything is allowed.
+
+**** 'requests' (array)
++
+Specifies a set of serivce instance pairs which the above client(s) is allowed/denied to communicate with.
+
+***** 'service'
++
+Specifies a service for the _requests_.
+
+***** 'instance'
++
+Specifies a instance for the _requests_
+
+**** 'offers' (array)
++
+Specifies a set of service instance pairs which are allowed/denied to be offered by the above client(s).
+
+***** 'service'
++
+Specifies a service for the _offers_.
+
+***** 'instance'
++
+Specifies a instance for the _offers_
+
+In the config/ folder are some vSomeIP configuration files to run the vSomeIP examples with activated security checks.
+They give a basic overview how to use the security related configuration tags described in this chapter to run a simple request/response or subscribe/notify example locally or over remote.
+
+Autoconfiguration
+-----------------
+vsomeip supports the automatic configuration of client identifiers and the routing.
+The first application that starts using vsomeip will automatically become the
+routing manager if it is _not_ explicitly configured. The client identifiers
+are generated from the diagnosis address that can be specified by defining
+DIAGNOSIS_ADDRESS when compiling vsomeip. vsomeip will use the diagnosis address
+as the high byte and enumerate the connecting applications within the low byte
+of the client identifier.
+
+Autoconfiguration of client identifiers isn't meant to be used together with vSomeIP Security.
+Every client running locally needs to have at least its own credentials configured when security is activated to ensure the credential checks can pass.
+Practically that means if a client requests its identifier over the autoconfiguration for which no credentials are configured (at least it isn't known which client identifier is used beforehand) it is impossible for that client to establish a connection to a server endpoint.
+However if the credentials for all clients are same it's possible to configure them for the overall (or DIAGNOSIS_ADDRESS) client identifier range to mix autoconfiguration together with activated security.
+
+vsomeipd
+--------
+The vsomeipd is a minimal vsomeip application intended to offer routing manager
+functionality on a node where one system wide configuration file is present.
+
+The vsomeipd uses the application name `vsomeipd` by default. This name can be
+overridden by specifying `-DROUTING=$DESIRED_NAME` during the cmake call.
+
+Example: Starting the daemon on a system where the system wide configuration is
+stored under `/etc/vsomeip.json`:
+[source, bash]
+----
+VSOMEIP_CONFIGURATION=/etc/vsomeip.json ./vsomeipd
+----
+
+When using the daemon it should be ensured that:
+
+* In the system wide configuration file the vsomeipd is defined as
+  routing manager, meaning it contains the line `"routing" : "vsomeipd"`.
+  If the default name is overridden the entry has to be adapted accordingly.
+  The system wide configuration file should contain the information about all
+  other offered services on the system as well.
+* There's no other vsomeip configuration file used on the system which contains
+  a `"routing"` entry. As there can only be one routing manager per system.
+
+
+vsomeip Hello World
+-------------------
+In this paragraph a Hello World program consisting out of a client and a service
+is developed. The client sends a message containing a string to the service.
+The service appends the received string to the string `Hello` and sends it back
+to the client.
+Upon receiving a response from the service the client prints the payload of the
+response ("Hello World").
+This example is intended to be run on the same host.
+
+All files listed here are contained in the `examples\hello_world` subdirectory.
+
+Build instructions
+~~~~~~~~~~~~~~~~~~
+The example can build with its own CMakeFile, please compile the vsomeip stack
+before hand as described in <<Compilation>>. Then compile the example starting
+from the repository root directory as followed:
+[source, bash]
+----
+cd examples/hello_world
+mkdir build
+cd build
+cmake ..
+make
+----
+
+Starting and expected output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting and expected output of service
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[source, bash]
+----
+$ VSOMEIP_CONFIGURATION=../helloworld-local.json \
+  VSOMEIP_APPLICATION_NAME=hello_world_service \
+  ./hello_world_service
+2015-04-01 11:31:13.248437 [info] Using configuration file: ../helloworld-local.json
+2015-04-01 11:31:13.248766 [debug] Routing endpoint at /tmp/vsomeip-0
+2015-04-01 11:31:13.248913 [info] Service Discovery disabled. Using static routing information.
+2015-04-01 11:31:13.248979 [debug] Application(hello_world_service, 4444) is initialized.
+2015-04-01 11:31:22.705010 [debug] Application/Client 5555 got registered!
+----
+
+Starting and expected output of client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[source, bash]
+----
+$ VSOMEIP_CONFIGURATION=../helloworld-local.json \
+  VSOMEIP_APPLICATION_NAME=hello_world_client \
+  ./hello_world_client
+2015-04-01 11:31:22.704166 [info] Using configuration file: ../helloworld-local.json
+2015-04-01 11:31:22.704417 [debug] Connecting to [0] at /tmp/vsomeip-0
+2015-04-01 11:31:22.704630 [debug] Listening at /tmp/vsomeip-5555
+2015-04-01 11:31:22.704680 [debug] Application(hello_world_client, 5555) is initialized.
+Sending: World
+Received: Hello World
+----
+
+CMakeFile
+~~~~~~~~~
+
+[source, bash]
+----
+include::../examples/hello_world/CMakeLists.txt[]
+----
+
+Configuration File For Client and Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[source, bash]
+----
+include::../examples/hello_world/helloworld-local.json[]
+----
+
+Service
+~~~~~~~
+
+[source, bash]
+----
+include::../examples/hello_world/hello_world_service.cpp[]
+----
+
+The service example results in the following program execution:
+
+:numbered!:
+
+[float]
+
+Main
+^^^^^
+
+. __main()__
++
+First the application is initialized. After the initialization is
+finished the application is started.
+
+[float]
+Initialization
+^^^^^^^^^^^^^^
+
+[start=2]
+. __init()__
++
+The initialization contains the registration of a message
+handler and an event handler.
++
+The message handler declares a callback (__on_message_cbk__) for messages that
+are sent to the specific service (specifying the service id, the service
+instance id and the service method id).
++
+The event handler declares a callback (__on_event_cbk__) for events that occur.
+One event can be the successful registration of the application at the runtime.
+
+[float]
+Start
+^^^^^
+
+[start=3]
+. __start()__
++
+The application will be started. This function only returns when the application
+will be stopped.
+
+[float]
+Callbacks
+^^^^^^^^^
+
+[start=4]
+. __on_state_cbk()__
++
+This function is called by the application when an state change occurred. If
+the application was successfully registered at the runtime then the specific
+service is offered.
+
+. __on_message_cbk()__
++
+This function is called when a message/request from a client for the specified
+service was received.
++
+First a response based upon the request is created.
+Afterwards the string 'Hello' will be concatenated with the payload of the
+client's request.
+After that the payload of the response is created. The payload data is set with
+the previously concatenated string.
+Finally the response is sent back to the client and the application is stopped.
+
+[float]
+Stop
+^^^^
+
+[start=6]
+. __stop()__
++
+This function stops offering the service, unregister the message and the event
+handler and shuts down the application.
+
+:numbered:
+
+Client
+~~~~~~
+[source, bash]
+----
+include::../examples/hello_world/hello_world_client.cpp[]
+----
+
+The client example results in the following program execution:
+
+:numbered!:
+
+[float]
+Main
+^^^^^
+
+. __main()__
++
+First the application is initialized. After the initialization is finished the
+application is started.
+
+[float]
+Initialization
+^^^^^^^^^^^^^^
+
+[start=2]
+. __init()__
++
+The initialization contains the registration of a message handler, an event
+handler and an availability handler.
++
+The event handler declares again a callback (__on_state_cbk__) for state changes
+that occur.
++
+The message handler declares a callback (__on_message_cbk__) for messages that
+are received from any service, any service instance and any method.
++
+The availability handler declares a callback (__on_availability_cbk__) which is
+called when the specific service is available (specifying the service id and the
+service instance id).
+
+[float]
+Start
+^^^^^
+
+[start=3]
+. __start()__
++
+The application will be started. This function only returns when the application
+will be stopped.
+
+[float]
+Callbacks
+^^^^^^^^^
+
+[start=4]
+. __on_state_cbk()__
++
+
+This function is called by the application when an state change occurred. If the
+application was successfully registered at the runtime then the specific service
+is requested.
+
+. __on_availability_cbk()__
++
+This function is called when the requested service is available or no longer
+available.
++
+First there is a check if the change of the availability is related to the
+'hello world service' and the availability changed to true.
+If the check is successful a service request is created and the appropriate
+service information are set (service id, service instance id, service method
+id).
+After that the payload of the request is created. The data of the payload is
+'World' and will be set afterwards.
+Finally the request is sent to the service.
+
+. __on_message_cbk()__
++
+This function is called when a message/response was received.
+If the response is from the requested service, of type 'RESPONSE' and the return
+code is 'OK' then the payload of the response is printed. Finally the
+application is stopped.
+
+[float]
+Stop
+^^^^
+
+[start=7]
+. __stop()__
++
+This function unregister the event and the message handler and shuts down the
+application.
+
+:numbered:
+
+Trace Connector
+---------------
+anchor:traceconnector[]
+
+Overview/Prerequisites
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Trace Connector is used to forward the internal messages that are sent over
+the Unix Domain Sockets to DLT. +
+So a prerequisite is that DLT is installed and the module can be found in 
+context of CMake.
+
+Configuration
+~~~~~~~~~~~~~
+
+Static Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+The Trace Connector can be configured statically over the 
+<<config-tracing,JSON configuration file>>. +
+
+[float]
+Example 1 (Minimal Configuration)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[source, bash]
+----
+{
+    ...
+
+    "tracing" :
+    {
+        "enable" : "true"
+    },
+
+    ...
+----
+
+This is the minimal configuration of the Trace Connector. This just enables the
+tracing and all of the sent internal messages will be traced/forwarded to DLT.
+
+[float]
+Example 2 (Using Filters)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[source, bash]
+----
+{
+    ...
+
+    "tracing" :
+    {
+        "enable" : "true",
+        "channels" : 
+        [
+            {
+                "name" : "My channel",
+                "id" : "MC"
+            }
+        ],
+        "filters" : [
+            {
+                "channel" : "MC",
+                "services" : [ "0x1234" ],
+                "methods" : [ "0x80e8" ],
+                "clients" : [ "0x1343" ],
+            }
+        ]
+    },
+
+    ...
+----
+
+You can apply filters to the messages. In this example only the messages that
+
+* are addressed to the service with the id _0x1234_
++
+* relates to the method with the id _0x80e8_ 
++
+* relates to the client with the id _0x1234_
+
+
+will be traced/forwarded to DLT. The messages will be forwarded over the channel
+with the id _MC_. If just one filter is used, then the definition of a channel is
+optional. But if multiple filters are used, each filter needs an own channel! +
+In this example each criteria has only one expression/value but it's also possible
+to define multiple values to get a more fine-grained filter. +
+The ids of the filter criterias can be found in the appropriate _.fdepl_ files
+and in the rest of the configuration file. +
+
+Dynamic Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+The Trace Connector can also be configured dynamically over its interfaces.
+
+[float]
+Example:
+^^^^^^^^
+
+[source, bash]
+----
+    // get trace connector
+    std::shared_ptr<tc::trace_connector> its_trace_connector = tc::trace_connector::get();
+
+    // add channel
+    its_trace_connector->add_channel("MC", "My channel");
+
+    //add filter rule
+    tc::trace_connector::filter_rule_t its_filter_rule;
+
+    its_filter_rule[tc::filter_criteria_e::SERVICES] = { 4660 };
+
+    its_filter_rule[tc::filter_criteria_e::METHODS] = { 33000 };
+    its_filter_rule[tc::filter_criteria_e::CLIENTS] = { 4931 };
+
+    its_trace_connector->add_filter_rule("MC", its_filter_rule);
+
+    // init trace connector    
+    its_trace_connector->init();
+
+    // enable trace connector
+    its_trace_connector->set_enabled(true);
+
+    //forward a message to DLT
+    its_trace_connector->forward_to_dlt(MESSAGE_TO_FORWARD);
+----
+
+Tools
+-----
+
+vsomeip_ctrl
+~~~~~~~~~~~~
+anchor:vsomeip_ctrl[]
+`vsomeip_ctrl` is a small utility which can be used to send SOME/IP messages
+from the commandline. If a response arrives within 5 seconds the response will
+be printed.
+
+* It can be build via `vsomeip_ctrl` make target (`make vsomeip_ctrl`).
+* The instance id of the target service has to be passed in hexadecimal
+  notation.
+* The complete message has to be passed in hexadecimal notation.
+* See the `--help` parameter for available options.
+* If `vsomeip_ctrl` is used to send messages to a remote service and no
+ `vsomeipd` is running on the local machine, make sure to pass a json
+ configuration file where `vsomeip_ctrl` is set as routing manager via
+ environment variable.
+* If `vsomeip_ctrl` is used to send messages to a local service and no
+ `vsomeipd` is running on the local machine, make sure to use the same json
+ configuration file as the local service.
+
+Example: Calling method with method id 0x80e8 on service with service id 0x1234,
+instance id 0x5678:
+[source, bash]
+----
+./vsomeip_ctrl --instance 5678 --message 123480e800000015134300030100000000000009efbbbf576f726c6400
+----
+
+Example: Sending a message to service with service id 0x1234, instance id
+0x5678 and method id 0x0bb8 via TCP
+[source, bash]
+----
+./vsomeip_ctrl --tcp --instance 5678 --message 12340bb8000000081344000101010000
+----