Author: jawi
Date: Tue Apr 29 10:06:24 2014
New Revision: 1590935
URL: http://svn.apache.org/r1590935
Log:
ACE-474 - added example on how to run a target.
Modified:
ace/site/trunk/content/user-doc/user-guide.mdtext
Modified: ace/site/trunk/content/user-doc/user-guide.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/user-guide.mdtext?rev=1590935&r1=1590934&r2=1590935&view=diff
==============================================================================
--- ace/site/trunk/content/user-doc/user-guide.mdtext (original)
+++ ace/site/trunk/content/user-doc/user-guide.mdtext Tue Apr 29 10:06:24 2014
@@ -100,14 +100,22 @@ Creating dynamic associations is current
## Running a target
-As mentioned, a target represents a client on which software can be deployed
by ACE. Actually, a target consists of an OSGi runtime that runs at least the
ACE management agent. This management agent periodically checks with the ACE
server whether or not new software is available. In case new software is
available for a target, it can automatically download and install it.
+As mentioned, a target represents a client on which software can be deployed
by ACE. Actually, a target consists of an OSGi runtime that runs *at least* the
ACE management agent. This management agent periodically checks with the ACE
server whether or not new software is available. In case new software is
available for a target, it can automatically download and install it.
ACE provides a runnable eclipse project, <tt>run-target</tt> that starts an
OSGi runtime, the ACE management agent, and a Gogo shell for easy debugging and
demo purposes. The management agent, or agent for short, itself can be found in
the <tt>org.apache.ace.agent</tt> project. This agent simply does the following:
1. it uploads the audit log of the target to the ACE server. The audit log
contains all changes in bundle and framework state, such as the starting and
stopping of the framework and (de)installation of bundles;
2. it check whether or not software updates are available. If so, it will
download it and install this update automatically.
-The agent can be configured by supplying it options through the command line
(e.g. <tt>-Dname=value</tt>):
+Since ACE 2.0.1, the binary distribution also contains a single-jar version of
a target, <tt>target.jar</tt>, that can be used to bootstrap the ACE management
agent on a target host as shown in the following example:
+
+ :::sh
+ $ java -Dagent.identification.agentid=target-1
-Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar
+ ____________________________
+ Welcome to Apache Felix Gogo
+ ...
+
+The agent can be configured by supplying its options as commandline parameters
(e.g. <tt>-Dname=value</tt>). A list of most used options are[^7]:
<tt>agent.identification.agentid</tt>
: defines the name to uniquely identify a target on the ACE server. In case
this option is not supplied, a default value of `defaultTargetID` is used;
@@ -115,23 +123,32 @@ The agent can be configured by supplying
<tt>agent.discovery.serverurls</tt>
: defines the ACE server URLs to connect to. Multiple URLs can be given to get
a form of fail-over: in case a connection to the first URL cannot be
established, the second URL will be used, and so on. If this option is given,
at least one URL should be supplied, and multiple URLs can be supplied by
separating them with a comma. If this option is omitted, a default value of
<tt>http://localhost:8080</tt> is used;
+<tt>agent.discovery.checking</tt>
+: defines whether or not server URLs should be checked whether they are alive
prior to being used. This implies that a "ping" request is sent to the server
URL that is going to be used. Server URLs that are not responding will not be
used and will cause another URL (defined by
<tt>agent.discovery.serverurls</tt>) to be picked instead. The default value is
<tt>true</tt>, which means that all server URLs are checked. Use <tt>false</tt>
if your ACE server(s) are not always available or when running the target on a
flacky network;
+
<tt>agent.logging.level</tt>
: defines the log level of the agent, and should be one of the following
values: <tt>DEBUG</tt>, <tt>INFO</tt>, <tt>WARNING</tt> or <tt>ERROR</tt>. The
default log level is <tt>INFO</tt>;
<tt>agent.controller.syncinterval</tt>
-: defines the interval (in seconds) in which the agent should synchronize with
the ACE server. A default of 60 seconds is used in case this option is not
supplied;
+: defines the interval (in seconds) in which the agent should synchronize with
the ACE server. A default of <tt>60</tt> seconds is used in case this option is
not supplied;
<tt>agent.controller.syncdelay</tt>
-: defines how long the agent should wait (in seconds) after startup before it
will synchronize with the ACE server for the first time. A default of 5 seconds
is used in case this option is not supplied;
+: defines how long the agent should wait (in seconds) after startup before it
will synchronize with the ACE server for the first time. A default of
<tt>5</tt> seconds is used in case this option is not supplied;
<tt>agent.controller.streaming</tt>
: if given a value of <tt>false</tt>, all software updates will be downloaded
completely first after which it will be installed. Use this value in case you
suffer from unreliable network connections. A value of <tt>true</tt> (the
default) causes the agent to download and install any software update directly.
<tt>agent.controller.fixpackages</tt>
-: if given a value of <tt>true</tt> (the default), software updates will only
contain the deltas or changed artifacts. For large deployment packages, this
can dramatically reduce the size of an update. Use a value of <tt>false</tt> to
get all artifacts for each software update;
+: if given a value of <tt>true</tt> (the default), software updates will only
contain the deltas or changed artifacts. For large deployment packages, this
can dramatically reduce the size of an update. Use a value of <tt>false</tt> to
*always* get *all* artifacts for *each* software update;
<tt>agent.controller.retries</tt>
-: defines the number of times the agent should retry to install a software
update in case its installation fails. If omitted, an installation is retried 3
times;
+: defines the number of times the agent should retry to install a software
update in case its installation fails. If omitted, an installation is retried
<tt>3</tt> times;
+
+<tt>agent.feedback.channels</tt>
+: defines what feedback channels exist and should be synchronized with the ACE
server. Feedback channels can be used to report any kind of information back to
the ACE server, and is by default used to provide basic information on the OSGi
environment to the ACE server. If omitted, the default of <tt>auditlog</tt> is
used. Multiple feedback channels can be supplied by separating them with
commas, like <tt>auditlog,myOwnLog</tt>. Note that all mentioned feedback
channels *must* be configured on the ACE server as well;
+
+<tt>agent.logging.events.exclude</tt>
+: defines the audit events that should be *excluded* from appearing on the
audit feedback channel. This parameter takes one or more event types
represented by integers separated by commas, for example,
<tt>2001,2003,2005,3001</tt>. By default, *no* events are excluded;
<tt>agent.connection.authtype</tt>
: defines how to connections to the server are to be authenticated. Valid
values are <tt>NONE</tt> for no authentication, <tt>BASIC</tt> for using
HTTP-BASIC authentication or <tt>CLIENTCERT</tt> for using client certificates.
In case this option is omitted, a value of <tt>NONE</tt> is assumed and no
authentication is used. In case of the values <tt>BASIC</tt> or
<tt>CLIENTCERT</tt>, additional options should be supplied (see below);
@@ -149,7 +166,7 @@ The agent can be configured by supplying
: provide the truststore file and password that contain the trusted (server)
certificate(s) for establishing a secure connection between agent and server.
-When the agent is started, a new target should appear in the ACE server after
you "Retrieve" the latest changes. If a target is added this way to the ACE
server (instead of adding it through the "Add targetâ¦" button), it initially
will be *unregistered*. This means that no metadata is present in the ACE
server yet and will not be created. To register a target, you can double click
the target to edit its properties. On the "Management" tab, you can check the
"Registered?" option (and optionally the "Auto approve?" option as well) and
close the dialog by pressing "Ok"[^3]. Once a target is registered, it cannot
be unregistered unless it is deleted (using the trash-icon).
+When the agent is started, a new target should appear in the ACE server after
you "Retrieve" the latest changes. Note that this can take a little while since
the agent needs to synchronize with the server first, see
<tt>agent.controller.syncdelay</tt> and <tt>agent.controller.syncinterval</tt>
options above. If a new target is seen this way by an ACE server instead of
adding it through the "Add targetâ¦" button, it initially will be
*unregistered*. This means that no metadata is present in the ACE server yet
and will not be created. To register a target, you can double click the target
to edit its properties. On the "Management" tab, you can check the
"Registered?" option (and optionally the "Auto approve?" option as well) and
close the dialog by pressing "Ok"[^3]. Once a target is registered, it cannot
be unregistered unless it is deleted (using the trash-icon).
### Using the template engine for targets
@@ -203,6 +220,7 @@ ACE will scan all configuration files an
[^6]: Apache Velocity is an engine that can generate documents by combining a
template with a context that contains variables. To learn more about it, visit
the [Velocity website](http://velocity.apache.org/).
+[^7]: All recognized options can be found in
`org.apache.ace.agent.AgentConstants`.
*[OBR]: OSGi Bundle Repository
