Routing Node Configuration File
The routing node (RN) configuration file is an XML file that controls the behavior of the RN and sets certain variables, such as timers, connection limits, and use case characteristics.
An example config file may be found in the AllJoyn source distribution in
../alljoyn_core/router/test/conf/sample.conf
Note that this sample configuration file would not be useful in practice. It is merely intended to provide an example of how various elements and attributes are formatted.
XML Schema
An XML schema, which may be used to validate config files, may be found on the AllSeen Alliance website:
https://allseenalliance.org/schemas/busconfig.xsd
The schema is also available in the source code distribution at:
../alljoyn_core/docs/busconfig.xsd
The schema may be referenced in config files by including the following
attributes in the busconfig (i.e., root) element:
<busconfig
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://allseenalliance.org/schemas/busconfig.xsd">
Default Configuration
Bundled Routing Node
The bundled routing node consists of a routing node and a Standard Client application that run in a single process.
As of v15.09, a user may compile AllJoyn with the scons variable TEST_CONFIG
set to an absolute or relative path to a config file. However, as suggested by
the scons variable name, this method is intended for debug and test purposes.
If the user does not provide a config file, then the bundled RN relies on a
hardcoded configuration contained in the file BundledRouter.cc.
Note that all config settings that apply to the standalone RN also apply to the bundled RN.
Bundled RN hardcoded configuration:
```xml
### Standalone Routing Node
The standalone RN runs as a compiled application named `alljoyn-daemon` on Linux.
If the user does not specify a separate configuration file when alljoyn-daemon
is started, or the `--internal` switch is used, then the RN will use a
configuration that is hardcoded in the source.
Note that the standalone RN is also available as a service on Windows 10. The
Windows 10 service uses a hard-coded configuration and does not accept any
parameters or switches. The examples in this document that describe passing
parameters or options to `alljoyn-daemon` are referring to the Linux
implementation.
**Example (Linux):** start routing node using internal config
./alljoyn-daemon
--OR--
./alljoyn-daemon --internal
**Standalone RN hardcoded configuration (Linux):**
```xml
<busconfig>
<type>alljoyn</type>
<listen>unix:abstract=alljoyn</listen>
<listen>tcp:iface=*,port=9955</listen>
<listen>udp:iface=*,port=9955</listen>
<limit name="auth_timeout">20000</limit>
<limit name="max_incomplete_connections">16</limit>
<limit name="max_completed_connections">32</limit>
<limit name="max_remote_clients_tcp">0</limit>
<limit name="max_remote_clients_udp">0</limit>
</busconfig>
Using an External Config File
As previously mentioned, a user-defined, external configuration file may be passed to a standalone RN. In order to start the standalone RN with an external configuration file, enter the following command (Linux):
./alljoyn-daemon --config-file=./my_rn_config.xml
Minimal Config File
A minimal config file requires the root element (<busconfig>) and a single
<listen> element.
For example:
<busconfig>
<listen>tcp:iface=*,port=9955</listen>
</busconfig>
This will result in a valid config file, but with very rudimentary
functionality. In fact, this configuration file would prevent the connection
of any leaf nodes, since it does not override the default values of 0 for
max_remote_clients_tcp and max_remote_clients_udp (i.e., <limit> attributes).
Therefore, it would only be able to connect to other routing nodes.
Review of Config File Elements and Attributes
The default configuration settings should be suitable for most use cases. However, some applications may benefit from using different settings. Therefore, the information below is intended to provide some guidance in using these settings.
The following is an alphabetical list of top-level XML
elements (i.e., immediate child elements of the root element <busconfig>)
available for use in the config file, along with a description of their meaning
and application. Any child elements will be described below their parent
element. Likewise for attributes.
<auth>
Not used by AllJoyn. Included for backward compatibility. Including this element in the config file will have no effect.
<flag>
Note: The content of the flag element may be either 'true' or 'false'. All flags default to 'false'
name attribute (required)
| name | description | default | Notes |
|---|---|---|---|
| ns_enable_v1 | enable legacy name service if true | true | Used for debugging. Do not use in deployed production applications. |
| ns_disable_ipv4 | disable IPv4 multicast if true | false | Used for debugging. Do not use in deployed production applications. |
| ns_disable_ipv6 | disable IPv6 multicast if true | false | Used for debugging. Do not use in deployed production applications. |
| ns_disable_directed_broadcast | disable subnet broadcast if true | false | Used for debugging. Do not use in deployed production applications. |
Examples
<flag name="ns_enable_v1">false</flag><flag name="ns_disable_ipv6">true</flag>
<fork>
The fork element is empty. It does not contain any content, child elements, or attributes.
If present in the config file, the routing node (daemon) will run in the background.
Note that <fork> must be enabled in order for <pidfile> to be effective.
On Linux, the config file setting for <fork> may be overridden from the
command line, by using the --fork or --no-fork options.
Examples
<fork/>
<include>
Specify the path to another configuration file, whose contents will be
included at the point where the <include> element is inserted.
The specified path may be absolute or relative. If the path is relative, then
it is relative to the configuration file using the
<include>.
In addition, the path must be to a file with the file
extension .conf.
ignore_missing attribute (optional)
May be set to "yes" or "no". The default is "no".
| ignore_missing | description |
|---|---|
| no (default) | a fatal error will occur if the file doesn't exist |
| yes | silently ignore if the file doesn't exist |
Examples
<include>../configs/my_config.conf</include><include ignore_missing="yes">my_config.conf</include><include ignore_missing="no">/home/bob/configs/my_config.conf</include>
<includedir>
Similar to <include>, except that, instead of specifying the path to a
file, specify the path to a directory containing configuration files.
All files with the .conf file extension will be included.
Note that the order in which the files in the directory are included is undefined and, therefore, users should avoid any config file include-order dependency when using this element.
The specified path may be absolute or relative. If the path is relative, then
it is relative to the configuration file using the
<includedir>
ignore_missing attribute (optional)
May be set to "yes" or "no". The default is "no".
| ignore_missing | description |
|---|---|
| no (default) | a fatal error will occur if the directory doesn't exist |
| yes | silently ignore if the directory doesn't exist |
Examples
<includedir>../configs</includedir><includedir ignore_missing="yes">configs</includedir><includedir ignore_missing="no">/home/bob/configs</includedir>
<limit>
Sets variables for various timeouts and connection limits to an unsigned, 32-bit integer.
name attribute (required)
| name | description |
|---|---|
| auth_timeout | The maximum amount of time that incoming connections are allowed to complete authentication. Beyond this limit, incoming connections may be aborted. |
| session_setup_timeout | The maximum amount of time that incoming connections are allowed to set up session routes. Beyond this limit, incoming connections may be disconnected. |
| max_incomplete_connections | The maximum number of incoming connections that can be in the process of authenticating. If starting to authenticate a new connection would mean exceeding this number, then the new connection will be dropped. |
| max_completed_connections | The maximum number of connections (inbound and outbound) allowed for each tranport. This means that the total number of completed connections allowed for TCP and UDP is twice this value. If starting to process a new connection would mean exceeding this number, then the new connection will be dropped. |
| max_remote_clients_tcp | The maximum number of remote clients using TCP. Note: this value must be overridden when using an external configuration file in order to enable TCP connections to leaf nodes. The default internal configuration file already overrides this value. Note that this setting may be useful for applications that have a specific requirement to prevent leaf nodes from connecting; however, for generic RNs, this value should not be zero. |
| max_remote_clients_udp | The maximum number of remote clients using UDP. Note: this value must be overridden when using an external configuration file in order to enable UDP connections to leaf nodes. The default internal configuration file already overrides this value. Note that this setting may be useful for applications that have a specific requirement to prevent leaf nodes from connecting; however, for generic RNs, this value should not be zero. |
Test hooks only
Many of the limits found in the source code are hooks for testing AllJoyn and are not useful for application development or end-products. For informational purposes, these are listed below, however, please do not use them for production code, as they may have undesirable or unpredictable behavior.
| DO NOT USE | |
|---|---|
| slap_min_idle_timeout | udp_timewait |
| slap_max_idle_timeout | udp_segbmax |
| slap_default_idle_timeout | udp_segmax |
| slap_max_probe_timeout | udp_fast_retransmit_ack_counter |
| slap_default_probe_timeout | sls_backoff |
| udp_connect_timeout | sls_backoff_linear |
| udp_connect_retries | sls_backoff_exponential |
| udp_initial_data_timeout | sls_backoff_max |
| udp_total_data_retry_timeout | sls_preferred_transports |
| udp_min_data_retries | tcp_default_probe_timeout |
| udp_persist_interval | tcp_min_idle_timeout |
| udp_total_app_timeout | tcp_max_idle_timeout |
| udp_link_timeout | tcp_default_idle_timeout |
| udp_keepalive_retries | tcp_max_probe_timeout |
| udp_delayed_ack_timeout | dt_min_idle_timeout |
| dt_max_idle_timeout | dt_default_idle_timeout |
| dt_max_probe_timeout | dt_default_probe_timeout |
Examples
<limit name="auth_timeout">20000</limit><limit name="max_incomplete_connections">16</limit>
<listen>
Identifies an address on which the bus attachment should listen for incoming connections. This address must be a valid URI that begins with an AllJoyn transport name, followed by appropriate parameters and options.
A configuration file must contain at least one
<listen> element. In addition, a configuration file may contain multiple
<listen> elements, including for the same transport, as long as the specified
transport and other parameters are valid and supported by the host platform.
Duplicate <listen> elements will be ignored (with a
warning message). Invalid <listen> elements
will result in a fatal error, unless there is a valid <listen> element
available, in which case the invalid <listen> element will be ignored (with a
warning message).
Descripton and Format
| Protocol or Transport Name |
|---|
| tcp |
| udp |
| unix |
| slap |
| npipe |
Format options
| Option Name |
|---|
| iface |
| addr |
| port |
| abstract |
| path |
| type |
| dev |
| baud |
<pidfile>
Records the routing node process ID (PID) to the specified file. If the file does not exist, it will be created. If the file does exist, it will be over-written.
IMPORTANT NOTE: <pidfile> is ONLY effective if <fork> is also
specified. Alternatively, the routing node may be started with the --fork
option (Linux).
<policy>
Defines a security policy to be applied to a particular
set of connections to the bus. A policy is made up of <allow> and <deny>
elements. Policies are analogous to a firewall in that they allow expected
traffic and prevent unexpected traffic.
Policies applied later will override those applied earlier, when the policies overlap.
Attributes
The <policy> element must include one of the following attributes, which are
mutually exclusive. A fatal error will be generated if more than one attribute
is present.
| Attribute | Contents |
|---|---|
| context | "default" OR "mandatory" |
| user | username or userid |
| group | group name or gid |
<allow> and <deny>
A <policy> must contain at least one <allow> or <deny> element. However,
a single <policy> with only an <allow> element is not meaningful for AllJoyn,
since all traffic is allowed by default. Instead, an <allow> element
primarily functions as an exception to previous <deny> elements.
Attributes for <allow> and <deny> elements
| Attribute |
|---|
| user |
| group |
| own |
| own_prefix |
| send_error / receive_error |
| send_interface / receive_interface |
| send_member / receive_member |
| send_path / receive_path |
| send_path_prefix / receive_path_prefix |
| send_group / receive_group |
| send_user |
| receive_user |
| send_same_user / receive_same_user |
| receive_sender / send_destination |
| send_type / receive_type |
Example
<policy context="default">
<deny user="*"/>
<deny own="*"/>
<deny send_type="method_call"/>
<allow send_type="signal"/>
<allow send_type="method_return"/>
<allow send_type="error"/>
<allow send_destination="org.freedesktop.DBus"/>
<allow receive_sender="org.freedesktop.DBus"/>
<allow send_interface="org.alljoyn.Bus.Peer.Session"/>
<allow user="jethro"/>
</policy>
<policy user="jethro">
<allow send_type="method_call"/>
<allow send_type="signal"/>
<allow send_type="method_return"/>
<allow send_type="error"/>
<allow own_prefix="test"/>
</policy>
<policy user="joe">
<deny send_type="method_call" send_user="beth"/>
<deny receive_type="signal" receive_user="bob"/>
</policy>
<property>
Define characteristics related to router node selection and nameservice.
name attribute (required)
| Name | Description | Default | Notes |
|---|---|---|---|
| router_node_connection | Used for routing node selection. One of the following: "access point", "wired", "wireless" |
"wireless" | If one of the enumerated values is not used, then the value will be ignored, a warning message will be logged, and the default value will be used |
| router_availability | Used for routing node selection. One of the following: "0-3 hr", "3-6 hr", "6-9 hr", "9-12 hr", "12-15 hr", "15-18 hr", "18-21 hr", "21-24 hr" |
"3-6 hr" | If one of the enumerated values is not used, then the value will be ignored, a warning message will be logged, and the default value will be used |
| router_mobility | Used for routing node selection. One of the following: "always stationary", "low mobility", "intermediate mobility", "high mobility" |
"intermediate mobility" | If one of the enumerated values is not used, then the value will be ignored, a warning message will be logged, and the default value will be used |
| router_power_source | Used for routing node selection. One of the following: "always ac powered", "battery powered and chargeable", "battery powered and not chargeable" |
"Battery powered and chargeable" | If one of the enumerated values is not used, then the value will be ignored, a warning message will be logged, and the default value will be used |
| router_advertisement_prefix | Used by thin core applications (TCA) to discover routing nodes. | "org.alljoyn.BusNode." |
In order to maximize availability to TCA, generic routing nodes should not modify this value. However, it may be useful when deploying custom systems that need to limit the TCA connecting to the routing node due to specific performance constraints. |
Example
<property name="router_power_source">Battery powered and chargeable</property>
<property name="router_mobility">Intermediate mobility</property>
<property name="router_availability">3-6 hr</property>
<property name="router_node_connection">Wireless</property>
<syslog>
Has no value or attributes. If present, indicates that AllJoyn Daemon should
send log messages to syslog.
Example
<syslog/>
<type>
Not used by AllJoyn. Included for backward compatibility. Including this element in the config file will have no effect.
<user>
Indicates that AllJoyn daemon should run as the indicated user instead of root. Note that the indicated user must be known to the system.
Example
<user>barts</user>