Configuration

This page explains how to configure WOSH on your system.

Note:
The configuration process is implemented within each WOSH Application. Because of that, it may change or even break the standard. Official WOSH Applications share the same strategy and format, as described further in this page.

Table of Contents:


Overview

WOSH system is made of a lot of components, their settings may be configured during initialization and at run-time.

WOSH settings are stored in folder /etc/wosh/.

WOSH database files (building, automations, users, ..) are not considered part of the system configuration and they are stored in /var/database/ folder (often in a specific sub-directory).

Main configuration file should be located in "/etc/wosh/wosh.APPLICATION.conf", it is the first file being loaded and usually defines only wosh::WoshKernel and Core-Modules settings, although it may define settings (not directives, see further) of any bundle.

WOSH Bundles are configured (and selected) using the apache2 strategy.

As user, you need to know only where configuration files are located and how they are interpreted (syntax), so they can be added/enabled/disabled and customized.

By a developer point of view, each component (such a core-module or a wosh::Bundle) refers to a setting group, stored as wosh::PropertiesProvider object by wosh::Settings class. Applications load (and parse) configuration files into WoshKernel::settings() instance, which will be inspected by components on their initialization.

After loading the main configuration file, Applications load any *.conf file from folder /etc/wosh/bundles-enabled by default (it may be customized) (using wosh::Settings::loadConfigurationFolder() method).

These settings are grouped pairs of key => value, each group refer to a component.

WOSH may be instructed to load a set of built-in bundles (or dynamically), this is managed by wosh::BundleManager and some custom directives.

wosh::BundleManager and wosh::BundleLoader will analyze *.load files from folder /etc/wosh/bundles-enabled.

Note:
Configuration (.conf) and loading (.load) files, as wosh.conf are formatted as POSIX standard (same as INI format on Windows).

wosh.conf

By default, wosh.conf contains some Kernel settings and directives, the most important configuration key is WoshKernel::Name. It must be unique in the network.

In order to load XML databases and to enable networking, some custom settings are required.

Please refer to wosh::Settings documentation for syntax and data format.

Warning:
Configuration file /etc/wosh/wosh.conf is usually missing or mis-configured. Even if it is included in the distribution, you should really take a look and update it.

The most importat fields should be customized are kernel's name and networking configuration. Default configuration should work already on most contexts, thanks to:

A sample configuration file is provided /etc/wosh/wosh.default.conf (prompt here).

###########################################################################
## Copyright (c) 2007-2011 - OpenSmartHome.com - WOSH
## All rights reserved.
##  open source, founded by Alessandro Polo
##  http://www.OpenSmartHome.com
##  http://www.AlessandroPolo.name
###########################################################################
# WOSH Framework - Configuration File - POSIX Format
# Revision $Id: wosh.default.conf 3768 2010-12-28 10:58:54Z alex $
###########################################################################

###########################################################################
# Formatting Information:
#  - Groups, Keys and values are case sensitive
#  - Value is formatted as wosh::Data string, see wosh::Data::fromString()
###########################################################################


###########################################################################
[WoshKernel]

# 'Name' key is VERY important, it must be set and UNIQUE in the whole network
#  Because of that, applications should be configured or launched with a custom option.
#  This requirement may be very weird while testing software or sharing configuration files.
#  But WoshKernel supports few MACROS: COMPUTER_NAME(), OS_NAME(), even combined with text.
#  MoreOver when input name is empty (unset) it will be initialized as 'wosh_{RANDOM_ID}'
#  See also NameAutoDiscovery
#
Name=$COMPUTER_NAME()

# 'NameAutoDiscovery' key is an optional field supported by most WOSH applications,
#  but disabled by default. Refer to 'Name' field as introduction.
#  This key will instruct the application to gather WOSH neighbours' name from the
#  the network (using the standard UDP protocol provided by DiscoveryUdpBundle).
#
NameAutoDiscovery=BOL(true)

# 'DebugLevel' is an optional, generic key and it is scoped for each object.
#
DebugLevel=VERBOSE

# 'BusType' is optional, refers to 'wosh.Bus.Core' which is initialized
# by the Kernel itself. Value is the class-name of the Bus to be allocated
# you should refer to wosh::BusManager::createBus method.
# Default value is 'wosh::BusRing' (the standard Bus implementation).
# Another built-in implementation is 'wosh::BusMT' (multi-thread polling bus)
#
BusType=wosh::BusRing

###########################################################################
[FileSystem]

# 'WoshRoot' points to the full local path of WOSH installation
# It is initially guessed by wosh::FileSystem and the parent of binary folder.
# The path is mapped to '$ROOT' alias.
# Note that this property will reset also core aliases (such as $DATABASE)
#
#WoshRoot=\shared\WOSH

# 'Aliases' definition List. Separator is ';'. Format is '<ALIAS>|<PATH>'
# aliases are very important because it is required by network operations
# The most common case is to define the Music archive on each system pointing
# to a network shared folder. This will allow the user to pick and play
# music files on any host of the network.
# Another very important alias is '$SHARED_TEMP', files are not (actually)
# copied (or transmitted) over the network. As the previous description
# all host should be able to access the same shared folder through this link.
# Example: $MUSIC|/archive/music;$SHARED_TEMP|Y:\WOSH\tmp_shared;
#
Aliases*=$MUSIC|Z:\music
Aliases*=$SHARED_TEMP|Y:\WOSH\tmp_shared

# Removes *.temp files in WOSH-TEMP folder on initializing
CleanTempOnBoot=BOL(true)

###########################################################################
[DeviceManager]

# 'EventLogLocallyOnly' key enables/disables logging of remote Device-events
# When enabled (default), Device Manager logs events from local-host only
#
EventLogLocallyOnly=BOL(true)

###########################################################################
[PersistenceManager]

# 'AutoLoadProtocols' definition List. Separator is ';'.
# EncoderProtocol (codecs) are usually loaded through allocators (as NetworkProtocols,
# and Bundles). Applications just install the built-in allocator.
# By default no codecs are installed. (But you will really need 'wosh::persistence::EncoderProtocolXml' protocol)
#
AutoLoadProtocols*=wosh::persistence::qt::EncoderProtocolXmlQt
AutoLoadProtocols*=wosh::persistence::plaintext::EncoderProtocolPlainText
AutoLoadProtocols*=wosh::persistence::html::EncoderProtocolHtmlDef
AutoLoadProtocols*=wosh::persistence::raw::EncoderProtocolRaw

###########################################################################
[UserManager]

# 'UsersDB' defines the path of Users' XML archive.
# Some users are created by the system itself {root, wosh, nobody, anonymous},
# but Properties are intersected with the archive.
# Default value is '$DATABASE/users/users.xml'
#
UsersDB=$DATABASE/users/users.xml

# 'GroupsDB' defines the path of Groups' XML archive.
# Some groups are created by the system itself {root, virtual, nobody, inhabitants},
# but Properties are intersected with the archive.
# Default value is '$DATABASE/users/groups.xml'
#
GroupsDB=$DATABASE/users/groups.xml

###########################################################################
[NetworkManager]

# 'AutoLoadProtocols' definition List. Separator is ';'.
# NetworkProtocols are usually loaded through allocators (as DataBases,
# and Bundles). Applications just install the built-in allocator.
# (such as NetworkProtocolAllocatorStatic)
# By default no NetworkProtocols are installed.
# WOSH comes with some built-in protocols as 'wosh::network::NetworkProtocolTcp', 'wosh::network::NetworkProtocolUdp'
#
AutoLoadProtocols*=wosh::network::NetworkProtocolTcp
AutoLoadProtocols*=wosh::network::NetworkProtocolUdp

# 'ListenChannels' definition List. Separator is ';'.
# This will tell the NetworkManager to listen (N) new channel(s).
# the NetworkProtocol is auto-selected (using NetworkProtocol:supportProtocol() call)
# Most protocols support the anycast binding (0.0.0.0), so you don't
# need to change it on each host. Read more on WOSH Documentation.
# Note that port must be the same in order to connect.
# Example: TCP://192.168.0.28:9595;UDP://192.168.0.28:9797
# Example: TCP://0.0.0.0:9595;UDP://0.0.0.0:9797
# Example: TCP://192.168.255.255:9595 will bind to the interface matching the mask.
# Example: TCP://192.168.0.12:9595+ will bind to the first valid port (starting with 9595).
#
ListenChannels=TCP://0.0.0.0:9595+

# 'StaticRoutes' definition List. Separator is ';'. Format is '<TARGET>:<FORWARDER>'
# Static routes are evaluated when <TARGET> host is not directly accessible,
# so the message will be sent to <FORWARDER> which will forward the message.
#
StaticRoutes=wosh169:wosh28; 

###########################################################################
[ThreadManager]

# 'ThreadMonitor' key enables/disables the ThreadManager-Monitor tool
# this component will periodically iterate Threads and evaluate their
# alive state (timestamp). A (warning-level) SystemError will be generated
# when a thread seems to be dead/crashed. See wosh::Thread specifications.
#
ThreadMonitor=BOL(true)

###########################################################################
[BusManager]

###########################################################################
[SystemLogger]

###########################################################################
[ObjectFactory]
LibraryFolders*=$LIBRARIES/bundles
LibraryFolders*=$LIBRARIES/framework
AutoLoadLibraries*=$LIBRARIES/bundles


###########################################################################
[SystemMonitor]

AutoLoadSystemInfoProxies*=wosh::communication::SystemInfoProxyDevices
AutoLoadSystemInfoProxies*=wosh::communication::SystemInfoProxyMessaging

###########################################################################
[SecurityManager]

###########################################################################
[BundleManager]

# 'AutoLoadBundles' is a flag which enables/disables the automatic execution
# of LOAD action from the folder defined by 'BundleLoadFolder' key.
# This is implemented by BundleLoader.
# Default value is 'BOL(false)'
#
AutoLoadBundles=BOL(true)

# 'AutoStartBundles' is a flag which enables/disables the automatic execution
# of START action after the loading process. You need to set also the flag
# 'AutoLoadBundles' to true.
# This is implemented by BundleLoader.
# Default value is 'BOL(false)'
#
AutoStartBundles=BOL(true)

# 'BundleLoadFolder' defines the folder containing '.load' files. They 
# list the action to be executed. Files are first parsed in alphabetical
# order generating an ordered list of Actions (such as LOAD, START).
# Once finished the actions are executed. This is implemented by BundleLoader.
# Default value is '$CONFIG/bundles-enabled'
#
BundleLoadFolder=$CONFIG/bundles-enabled

# Note that Bundles configuration is not loaded by this flow, Applications
# explicitly load the bundles' configuration folder into global Settings
# just after loading this file (wosh.conf).
# 'BundleLoadFolder' defines the folder containing '.conf' files. On
# BundleManager initialization, the folder will be processed adding
# groups the WoshKernel default Settings.
# They aren't apply at this point, but only after loading them.
# Note that 'AutoLoadBundles' flag must be enabled in order to forward
# settings (Properties) to loaded Bundles.
# Note that some Bundles have requirements (means they need another Bundle
# to work properly), in future there will be more dependency checks and recovery.
# Anyway the parsing order is by filename.
# Default value is '$CONFIG/bundles-enabled'
#
BundleConfigFolder=$CONFIG/bundles-enabled

###########################################################################
# You may write settings of each Bundle (as group) here.
# WOSH Standard specification suggests to place each settings group in a
# separate (.conf) file located in bundles-enabled folder.
# And the BundleManager directives as another (.load) file.
# 
#



Bundles configuration

Bundles are services (aka components) of the WOSH system.

You may see them as applications running over WOSH layer, because of that they probably need to be configured with custom settings. Moreover, since most WOSH Applications are able to load services dynamically (at boot), administrator has to select which bundles should be selected and started.

You may read Bundles for more technical information.

Bundles need to be loaded (created), configured (apply settings) and eventually started. This process is managed by wosh::BundleManager and its helpers (such as wosh::BundleLoader), but applications (such as woshshop) may force (hard-coded) inclusion of some compoenents into the kernel.

Bundle's configuration (settings) and their initializazion directives (such as BundleLoad BundleStart) are placed by default in the same folder (/etc/wosh/bundles-enabled) as two different files, administrator may change the path in the main configuration file (wosh.conf):

As said, the configuration/loading strategy is very similar to apache2 (I find it amazing), default configuration/loading files (the ones you take as template) are located in /etc/wosh/bundles-available folder. Basically, to install a new bundle, you just need to copy such template into bundle-enabled folder and update its configuration.

On initialization, wosh::BundleManager loads the configuration folder ( BundleConfigFolder ) and adds settings-groups (there should be one for each bundle) to global settings-database (into WoshKernel).

Then, if AutoLoadBundles flag is enabled (default), it will parse BundleLoadFolder folder and enqueue the actions (alphanumerical-ordered by their source filename). Moreover all LOAD action will be executed. A LOAD action is formatted as:

BundleLoad wosh::interfaces::network::Discovery

where wosh::interfaces::network::Discovery is the (class) type of the Bundle to be loaded. Since there may be more instances of some type of bundles, you may assign its name (and you must do it here) using the syntax:

BundleLoad wosh::interfaces::entertainment::PlayerGStreamer PlayerKitchen

this will create a wosh::bundle::PlayerGStreamerBundle instance and assign the name PlayerKitchen

Note that the classname in this example is a pure interface, because of that ObjectFactory core-module will find the nearest matching implementation. Instead of that (to ensure the system will load a specific implementation), you may specify the final classname of the bundle:

BundleLoad wosh::bundles::DiscoveryUdpBundle DiscoveryUdp

Once bundles are loaded, BundleManager will forward their settings (Properties) as defined (grouped) in global settings (which were loaded in previous step).

wosh::BundleManager is ready to start bundles for you if the AutoStartBundles flag is enabled. The command to start a bundle looks like:

BundleStart PlayerDoccia

Here you must pass the bundle's name assigned BundleLoad. Again, the action is not performed while parsing, but is delayed and the iteration is ordered as the loading process (by filename).

Some more notes:

Final words.. configuration and loading filenames are standardized in WOSH, you should follow the standard (similar to init.d of Linux systems).

<NUMBER:[0,999]>_<BUNDLE:TYPE(simplified)>.<EXTENSION{.conf;.load}>

An example is 001_DiscoveryUdp.conf and 001_DiscoveryUdp.load The number at the beginning let the user to easily insert and move items, changing the start-up order of bundles (alphanumerical order).

A sample Bundle's configuration file is prompted here (/etc/wosh/bundles-available/001_DiscoveryUdp.conf)

###########################################################################
## Copyright (c) 2007-2011 - OpenSmartHome.com - WOSH
## All rights reserved.
##  open source, founded by Alessandro Polo
##  http://www.OpenSmartHome.com
##  http://www.AlessandroPolo.name
###########################################################################
# WOSH Framework - Configuration File - POSIX Format
# Revision $Id: 001_DiscoveryUdp.conf 3341 2010-09-28 21:00:46Z alex $
###########################################################################
# Properties of Bundle named 'DiscoveryUdp'
###########################################################################

[DiscoveryUdp]

# 'BindAddressPort' ket defines the address and port to bind the socket to
# Address format is <IPv4-ADDRESS>:<PORT>
# Anycast is supported as '0.0.0.0:8787' and will listen on any interface.
# Default value is '0.0.0.0:8787'
#
BindAddressPort=0.0.0.0:8787+

# 'BroadcastAddressPortList' definition List. Separator is ';'.
# Defines the addresses to send the discovery packet to.
# Address format is <IPv4-ADDRESS>:<PORT>
# Broadcast is supported as full broadcast (255.255.255.255)
# or against last subnet (a.b.c.255).
# Default value is '255.255.255.255:8787'
#
BroadcastAddressPortList*=192.168.0.255:8787
BroadcastAddressPortList*=169.254.2.255:8787

# 'NotifyFrequency' is the discovery notification period in seconds,
# casted as integer. 
# Default value is 'INT(60)'
#
NotifyFrequency=INT(60)


AlwaysReplyNewHosts=BOL(true)

A sample Bundle's loading file is prompted here (/etc/wosh/bundles-available/001_DiscoveryUdp.load)

###########################################################################
## Copyright (c) 2007-2011 - OpenSmartHome.com - WOSH
## All rights reserved.
##  open source, founded by Alessandro Polo
##  http://www.OpenSmartHome.com
##  http://www.AlessandroPolo.name
###########################################################################
# WOSH Framework - Configuration File - POSIX Format
# Revision $Id: 001_DiscoveryUdp.load 3027 2010-09-01 05:53:30Z alex $
###########################################################################
# Directives for 'wosh::bundles::DiscoveryUdpBundle',
# Only one instance, (friendly) called DiscoveryUdp.
###########################################################################


# load Bundle of type 'wosh::bundles::DiscoveryUdpBundle' and name it 'DiscoveryUdp'
#
BundleLoad wosh::bundles::DiscoveryUdpBundle DiscoveryUdp


# start the Bundle named 'DiscoveryUdp'
#
BundleStart DiscoveryUdp

Loading and configuration of many bundles may also be grouped in two files, as shown in 020_PlayerGStreamer.load and 020_PlayerGStreamer.conf.

Note:
Log files may help you finding mis-configuration and detecting errors.

Database & Persistence

While configuration files are global and 'read-only' (applied once, never overwritten), but there are also many other custom settings and inputs (usually related to bundles). Some examples are:

Default database folder is defined as $DATABASE (nested alias of $ROOT/var/database).

WOSH database sets must be stored in any WOSH-compatible format (such as XML).

Refer to Persistence and WOSH Persistence Framework.


Generated on Sat Feb 26 2011 11:28:29 for WOSH system 0.8.888 [phoenix] by Alessandro Polo, using DoxyGen 1.7.2 hosted by WOSH Framework