ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r907281 - in /websites/staging/ace/trunk/content: ./ user-doc/user-guide.html
Date Tue, 29 Apr 2014 10:06:29 GMT
Author: buildbot
Date: Tue Apr 29 10:06:29 2014
New Revision: 907281

Log:
Staging update by buildbot for ace

Modified:
    websites/staging/ace/trunk/content/   (props changed)
    websites/staging/ace/trunk/content/user-doc/user-guide.html

Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Apr 29 10:06:29 2014
@@ -1 +1 @@
-1590009
+1590935

Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html
==============================================================================
--- websites/staging/ace/trunk/content/user-doc/user-guide.html (original)
+++ websites/staging/ace/trunk/content/user-doc/user-guide.html Tue Apr 29 10:06:29 2014
@@ -246,30 +246,44 @@ To delete an association once is created
 <strong>Figure 6</strong>: Creating a static association by dragging a particular
version of a bundle onto a feature.</p>
 <p>Creating dynamic associations is currently only supported for bundle artifacts.
For other types of artifacts, such as configuration files, only static associations can be
created<sup id="fnref:2"><a class="footnote-ref" href="#fn:2" rel="footnote">2</a></sup>.
</p>
 <h2 id="running-a-target">Running a target</h2>
-<p>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.</p>
+<p>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 <em>at least</em>
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.</p>
 <p>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:</p>
 <ol>
 <li>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;</li>
 <li>it check whether or not software updates are available. If so, it will download
it and install this update automatically.</li>
 </ol>
-<p>The agent can be configured by supplying it options through the command line (e.g.
<tt>-Dname=value</tt>):</p>
+<p>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:</p>
+<div class="codehilite"><pre><span class="nv">$ </span>java -Dagent.identification.agentid<span
class="o">=</span>target-1 -Dagent.discovery.serverurls<span class="o">=</span>http://my.ace.server:8080
-jar target.jar
+____________________________
+Welcome to Apache Felix Gogo
+...
+</pre></div>
+
+
+<p>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<sup id="fnref:7"><a
class="footnote-ref" href="#fn:7" rel="footnote">7</a></sup>:</p>
 <dl>
 <dt><tt>agent.identification.agentid</tt></dt>
 <dd>defines the name to uniquely identify a target on the ACE server. In case this
option is not supplied, a default value of <code>defaultTargetID</code> is used;</dd>
 <dt><tt>agent.discovery.serverurls</tt></dt>
 <dd>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;</dd>
+<dt><tt>agent.discovery.checking</tt></dt>
+<dd>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;</dd>
 <dt><tt>agent.logging.level</tt></dt>
 <dd>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>;</dd>
 <dt><tt>agent.controller.syncinterval</tt></dt>
-<dd>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;</dd>
+<dd>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;</dd>
 <dt><tt>agent.controller.syncdelay</tt></dt>
-<dd>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;</dd>
+<dd>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;</dd>
 <dt><tt>agent.controller.streaming</tt></dt>
 <dd>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.</dd>
 <dt><tt>agent.controller.fixpackages</tt></dt>
-<dd>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;</dd>
+<dd>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 <em>always</em>
get <em>all</em> artifacts for <em>each</em> software update;</dd>
 <dt><tt>agent.controller.retries</tt></dt>
-<dd>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;</dd>
+<dd>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;</dd>
+<dt><tt>agent.feedback.channels</tt></dt>
+<dd>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 <em>must</em> be configured on the ACE
server as well;</dd>
+<dt><tt>agent.logging.events.exclude</tt></dt>
+<dd>defines the audit events that should be <em>excluded</em> 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,
<em>no</em> events are excluded;</dd>
 <dt><tt>agent.connection.authtype</tt></dt>
 <dd>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);</dd>
 <dt><tt>agent.connection.username</tt> and <tt>agent.connection.password</tt></dt>
@@ -281,7 +295,7 @@ To delete an association once is created
 <dt><tt>agent.connection.trustfile</tt> and <tt>agent.connection.trustpass</tt></dt>
 <dd>provide the truststore file and password that contain the trusted (server) certificate(s)
for establishing a secure connection between agent and server.</dd>
 </dl>
-<p>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 <em>unregistered</em>.
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"<sup id="fnref:3"><a class="footnote-ref" href="#fn:3"
rel="footnote">3</a></sup>. Once a target is registered, it cannot be unregistered
unless it is deleted (using the trash-icon).</p>
+<p>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 <em>unregistered</em>. 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"<sup
id="fnref:3"><a class="footnote-ref" href="#fn:3" rel="footnote">3</a></sup>.
Once a target is registered, it cannot be unregistered unless it is deleted (using the trash-icon).</p>
 <h3 id="using-the-template-engine-for-targets">Using the template engine for targets</h3>
 <p>If you want to provision software to multiple targets, those targets probably need
to have their own specific configuration. For example, the IP address on which it should listen
for web requests, or the credentials to access a database. One could create specific configuration
files for each target, however, this can become quite tedious if you have lots of targets.
Besides that, ACE requires that each artifact has a unique name, so you need to create unique
file names for your configuration files for each change you make. Fortunately, ACE provides
an easier way to solve this problem: a template engine.</p>
 <p>All configuration files<sup id="fnref:4"><a class="footnote-ref" href="#fn:4"
rel="footnote">4</a></sup> can be regarded as templates, in which variables
are replaced with values supplied by ACE. In fact, the values are definable per target, distribution,
feature or artifact and ACE will collect all tags of entities that are associated with a specific
target. To define variables and their replacement values (or "tags") for, for example, a distribution,
open up its properties dialog by double clicking on it, and selecting the "Tag Editor" tab.
Each line in this editor represents a tag. The key of a tag defines that (part of) the variable
name to be replaced in configuration files, and the value of a tag the actual replacement
value.<br />
@@ -332,6 +346,9 @@ In order to let ACE provision your (temp
 <li id="fn:6">
 <p>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 <a href="http://velocity.apache.org/">Velocity
website</a>.&#160;<a class="footnote-backref" href="#fnref:6" rev="footnote"
title="Jump back to footnote 6 in the text">&#8617;</a></p>
 </li>
+<li id="fn:7">
+<p>All recognized options can be found in <code>org.apache.ace.agent.AgentConstants</code>.&#160;<a
class="footnote-backref" href="#fnref:7" rev="footnote" title="Jump back to footnote 7 in
the text">&#8617;</a></p>
+</li>
 </ol>
 </div></div>
       <hr>



Mime
View raw message