Embedded Support

Embedded support addresses the cases where the machines already exist or are created manually.
Therefore, it covers existing (physical) machines, devices (such as cards) and virtual machines created manually (e.g. with Virtual Box).

To install it, open the DM’s interactive mode and use one of the following options.
With the roboconf:target command:

# The version will be deduced automatically by the DM
roboconf:target embedded

Or with the native Karaf commands:

# Here in version 0.9
bundle:install --start mvn:net.roboconf/roboconf-target-embedded/0.9

With this configuration, you need to start the agent directly.
And you will have to pass it some information by hand (like the IP address of the messaging server).
This is achieved by updating the net.roboconf.agent.configuration.cfg file under Karaf’s etc directory.

Sample target.properties.
Just copy / paste and edit.

# Configuration file for Embedded Machines
handler = embedded
id = a unique identifier
name = 
description = 

# Options if remote machines should be used and configured by SSH.

# A list/pool of IP addresses
#embedded.ip = 

# The SSH key file
# (~/.ssh/id_rsa and ~/.ssh/id_dsa are used by default).
#scp.keyfile = 

# The file that lists known hosts
# (~/.ssh/known_hosts by default).
#scp.known.hosts.file = ~/.ssh/known_hosts

# The user name (ubuntu by default)
#scp.user = ubuntu

# Disable hosts validation.
#scp.disable.host.validation = false

# Specify fingerprint for hosts validation.
#hostkey.host1 = 
#hostkey.host2 = 

# The directory that contains the agent''s configuration
# (default is "/etc/roboconf-agent").
#scp.agent.configdir = /etc/roboconf-agent

Here is a complete description of the parameters for Embedded.

Property	Description	Default	Mandatory
handler	Determines the target handler to use	none, must be “embedded”	yes
id	A unique identifier for the target properties.	-	yes
name	A human-readable name for the target	-	no
description	A description of the target.	-	no
embedded.ip	A list of comma-separated IP addresses, that refer to hosts with Roboconf agents installed (an IP will be automatically selected when needed, and user-data transferred there using SCP).	-	no
scp.user	A SCP user name, to transfer user-data to a remote host referenced in the IP list (see embedded.ip).	ubuntu	no
scp.keyfile	A SCP key file (.pem or so), to transfer user-data to a remote host referenced in the IP list (see the embedded.ip section).	~/.ssh/id_rsa and ~/.ssh/id_dsa	no
scp.known.hosts.file	A file that lists known hosts.	~/.ssh/known_hosts	no
scp.disable.host.validation	True to disable hosts validation (e.g. known hosts and unknown hosts will be accepted and trusted without verification).	false	no
hostkey.<host>	A template property to specify the fingerprint for a given host. This is an alternative to known hosts. See an example below.	-	no
scp.agent.configdir	The directory that contains agent configuration on the remote host.	/etc/roboconf-agent	no

Focus on embedded.ip

This property allows Roboconf to dynamically pick up an idle Roboconf agent from a pool of machines. This target handler uses SCP to configure the agent and give it an identity (which application and which instance it manages).

When such a machine is terminated in Roboconf, the agent’s configuration is reset, which is equivalent to recycling the agent for another usage. During the reset operation, the agent tries to uninstall everything was left installed from the previous application.

Be careful about user permissions.

The SCP connection tries to create / overwrite two files.

net.roboconf.agent.configuration.cfg, expected to be in the directory associated with the scp.agent.configdir parameter.
A properties file which is generated by the target handler and uploaded to the remote machine in the same directory (scp.agent.configdir).

To prevent issues, it is important that the SCP user has the right permissions to create or update these files.
Here is an example of commands to use when preparing the machines for the pool.

# Go into the agent's configuration directory
cd /etc/roboconf-agent

# Assuming we use "ubuntu" as our SCP user
chown ubuntu net.roboconf.agent.configuration.cfg
chmod 744 net.roboconf.agent.configuration.cfg

# Deal with the second file
touch roboconf-agent-parameters.properties
chown ubuntu roboconf-agent-parameters.properties
chmod 744 roboconf-agent-parameters.properties

Host Verification

When a SSH connection is established to configure a remote machine (see the embedded.ip section), it needs to verify the machine is what it pretends to be.

There are three possible strategies:

Indicate the path of a known_hosts file (scp.known.hosts.file property).
Disable host verification (not safe, but possible - scp.disable.host.validation property).
Eventually, you can specify, for each IP address or host name, the expected fingerprint (properties prefixed with hostkey.).

The following snippet shows how host verification can be done with hosts finger prints directly in the target properties.

# ...

# A list/pool of IP addresses
embedded.ip = host1, host2

# ...

# Specify fingerprints for hosts validation.
hostkey.host1 = fe:0a:4b:7b:77:67:0e:63:b0:0b:a2:3b:a1:73:38:64
hostkey.host2 = 04:0a:1b:7b:7b:cc:0a:61:b0:0b:a2:55:a2:43:98:61