Author: jawi
Date: Thu Oct 31 14:49:07 2013
New Revision: 1537513
URL: http://svn.apache.org/r1537513
Log:
Minor markup updates.
Modified:
ace/site/trunk/content/dev-doc/configuring-relay-servers.mdtext
Modified: ace/site/trunk/content/dev-doc/configuring-relay-servers.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/configuring-relay-servers.mdtext?rev=1537513&r1=1537512&r2=1537513&view=diff
==============================================================================
--- ace/site/trunk/content/dev-doc/configuring-relay-servers.mdtext (original)
+++ ace/site/trunk/content/dev-doc/configuring-relay-servers.mdtext Thu Oct 31
14:49:07 2013
@@ -16,25 +16,25 @@ In situations where lots of targets need
Note that target logs need to be propagated to the main ACE server in order to
make this information available for further inspection. For example, a target
operator might want to know the current status of a target, even if this target
is not directly served by the main ACE server.
-An ACE relay server is a stripped down ACE server that only includes the bare
minimum functionality to serve its targets. In addition to accepting
log-updates from targets and provisioning software updates to its targets, it
relays log information it received from its targets to the upstream ACE server
and replicates (at least) the `deployment` repository from the upstream ACE
server for its own use. A schematic overview of the functional blocks in a
relay server is shown in figure 2: {#fig2}
+An ACE relay server is a stripped down ACE server that only includes the bare
minimum functionality to serve its targets. In addition to accepting
log-updates from targets and provisioning software updates to its targets, it
relays log information it received from its targets to the upstream ACE server
and replicates (at least) the <tt>deployment</tt> repository from the upstream
ACE server for its own use. A schematic overview of the functional blocks in a
relay server is shown in figure 2: {#fig2}
**Figure 2**: A functional overview of how a relay server functions.
-In the following sections, each of these functional blocks will be explained
in more depth along with how to configure them. The configuration examples are
shown as simple key-value pairs separated with an equals (`=`) sign. Lines
starting with a hash (`#`) are considered comments.
+In the following sections, each of these functional blocks will be explained
in more depth along with how to configure them. The configuration examples are
shown as simple key-value pairs separated with an equals (<tt>=</tt>) sign.
Lines starting with a hash (<tt>#</tt>) are considered comments.
## Log synchronisation between target and relay
Like in a single-server scenario, the relay must allow a target to upload its
log before it can be synchronised with the main ACE server.
-To configure the storage of logs from targets on the relay server, we need to
instantiate a log store by supplying the following configuration to the
`org.apache.ace.log.server.store.factory` managed service factory:
+To configure the storage of logs from targets on the relay server, we need to
instantiate a log store by supplying the following configuration to the
<tt>org.apache.ace.log.server.store.factory</tt> managed service factory:
# a symbolic name used to reference to this store from other services
name=auditlog
-This will instantiate a new log store service named `auditlog`[^1] that can be
used to store the log information of targets.
+This will instantiate a new log store service named <tt>auditlog</tt>[^1] that
can be used to store the log information of targets.
-To allow targets to upload their logs to the relay server, a log-servlet needs
to be instantiated. This is done by supplying the following configuration to
the `org.apache.ace.log.server.servlet.factory` managed service factory:
+To allow targets to upload their logs to the relay server, a log-servlet needs
to be instantiated. This is done by supplying the following configuration to
the <tt>org.apache.ace.log.server.servlet.factory</tt> managed service factory:
# the symbolic name of the actual log store to store the uploaded logs in
name=auditlog
@@ -43,24 +43,24 @@ To allow targets to upload their logs to
# whether or not to use authentication
authentication.enabled=false
-This will instantiate a servlet that listens on the `/auditlog`[^2] endpoint
(for example, `http://my.relay.server:8080/auditlog`). The given `name`
configuration key is used to lookup the actual log store we've created
previously.
+This will instantiate a servlet that listens on the <tt>/auditlog</tt>[^2]
endpoint (for example, <tt>http://my.relay.server:8080/auditlog</tt>). The
given <tt>name</tt> configuration key is used to lookup the actual log store
we've created previously.
## Log synchronisation between relay and main server
-With the log store and servlet configured and in place, a target is now able
to synchronise its logs with the relay server. However, once uploaded to the
relay server, the logs will not propagate automatically to the main ACE server.
A separate log-synchronisation task is responsible for this. To enable this
task, we need to supply the following configuration to the
`org.apache.ace.log.server.task.factory` managed service factory:
+With the log store and servlet configured and in place, a target is now able
to synchronise its logs with the relay server. However, once uploaded to the
relay server, the logs will not propagate automatically to the main ACE server.
A separate log-synchronisation task is responsible for this. To enable this
task, we need to supply the following configuration to the
<tt>org.apache.ace.log.server.task.factory</tt> managed service factory:
# the symbolic name of the actual log store to synchronise
name=auditlog
# how to synchronise logs, can be 'pull', 'push' or 'pushpull'
mode=push
-This will create a "task" service that will push all log information from the
`auditlog`[^1] store to the main server. The `mode` configuration key denotes
how to synchronise with the main server:
+This will create a "task" service that will push all log information from the
<tt>auditlog</tt>[^1] store to the main server. The <tt>mode</tt> configuration
key denotes how to synchronise with the main server:
-* `push` synchronises (or "pushes") the logs from the relay server to the main
server and is typically used in a relaying situation as described in this
document;
-* `pull` synchronises (or "pulls") the logs from the main server to the relay
server and is typically used to create secondary backup servers and is not
further discussed in this document;
-* `pushpull` will perform a two-way synchronisation between relay and main
server and can be used to support fail-over situations.
+* <tt>push</tt> synchronises (or "pushes") the logs from the relay server to
the main server and is typically used in a relaying situation as described in
this document;
+* <tt>pull</tt> synchronises (or "pulls") the logs from the main server to the
relay server and is typically used to create secondary backup servers and is
not further discussed in this document;
+* <tt>pushpull</tt> will perform a two-way synchronisation between relay and
main server and can be used to support fail-over situations.
-In addition, the log synchronisation task (and other tasks as well, see below)
needs to know what upstream server it should synchronise with. For this
information, it uses the ACE discovery service, which is configured by
supplying, for example, the following configuration to the
`org.apache.discovery.property`[^3] managed service:
+In addition, the log synchronisation task (and other tasks as well, see below)
needs to know what upstream server it should synchronise with. For this
information, it uses the ACE discovery service, which is configured by
supplying, for example, the following configuration to the
<tt>org.apache.discovery.property</tt>[^3] managed service:
# what is the URL to the *main* ACE server
serverURL = http://my.main.server:8080
@@ -69,7 +69,7 @@ In addition, the log synchronisation tas
The relay needs to have at least a deployment repository[^4]. This repository
is a verbatim copy of the deployment repository on the master server and as
such needs to be replicated periodically. The configuration of the deployment
provider consists of three parts: a repository store, the repository servlet,
and a repository provider.
-To create a "slave" deployment repository[^5] store, the following
configuration needs to be supplied to the
`org.apache.ace.server.repository.factory` managed service factory:
+To create a "slave" deployment repository[^5] store, the following
configuration needs to be supplied to the
<tt>org.apache.ace.server.repository.factory</tt> managed service factory:
# the symbolic name of the repository, should be "deployment"
name=deployment
@@ -78,16 +78,16 @@ To create a "slave" deployment repositor
# indicates that this is a slave/read-only repository
master=false
-To make the repository store accessible through a servlet, we need to supply
the following configuration to the
`org.apache.ace.repository.servlet.RepositoryServlet` managed service:
+To make the repository store accessible through a servlet, we need to supply
the following configuration to the
<tt>org.apache.ace.repository.servlet.RepositoryServlet</tt> managed service:
# the endpoint on which the deployment repository store is accessible
org.apache.ace.server.servlet.endpoint=/repository
# whether or not to enable authentication for this endpoint
authentication.enabled = false
-This will instantiate a servlet that listens on the `/repository` endpoint
(for example, `http://my.relay.server:8080/repository`).
+This will instantiate a servlet that listens on the <tt>/repository</tt>
endpoint (for example, <tt>http://my.relay.server:8080/repository</tt>).
-With the repository store and servlet configured, we can configure the
deployment repository provider, which is used to collect information about
deployment artefacts that should be deployed on a target. The deployment
repository provider is configured by supplying the following configuration to
the `org.apache.ace.deployment.provider.repositorybased` managed service:
+With the repository store and servlet configured, we can configure the
deployment repository provider, which is used to collect information about
deployment artefacts that should be deployed on a target. The deployment
repository provider is configured by supplying the following configuration to
the <tt>org.apache.ace.deployment.provider.repositorybased</tt> managed service:
# the URL on which the deployment repository store can be accessed
url = http://my.relay.server:8080/repository
@@ -100,14 +100,14 @@ With the repository store and servlet co
The target is only interested in downloading deployment packages containing
the updates for its software and/or its management agent. To support this, two
servlets need to be instantiated, one for accessing the deployment packages of
the target software, and one for accessing the deployment packages for the
management agent.
-To configure the servlet responsible for providing deployment packages of the
target software, we need to supply the following configuration to the
`org.apache.ace.deployment.servlet` managed service:
+To configure the servlet responsible for providing deployment packages of the
target software, we need to supply the following configuration to the
<tt>org.apache.ace.deployment.servlet</tt> managed service:
# the endpoint on which the deployment servlet for software-updates is
accessible
org.apache.ace.server.servlet.endpoint=/deployment
# whether or not to enable authentication for this endpoint
authentication.enabled = false
-To configure the servlet responsible for providing agent updates, we need to
supply the following configuration to the
`org.apache.ace.deployment.servlet.agent` managed service:
+To configure the servlet responsible for providing agent updates, we need to
supply the following configuration to the
<tt>org.apache.ace.deployment.servlet.agent</tt> managed service:
# the endpoint on which the deployment servlet for agent-updates is
accessible
org.apache.ace.server.servlet.endpoint=/agent
@@ -118,7 +118,7 @@ To configure the servlet responsible for
## Task scheduler
-With the synchronisation and repository replication tasks in place, we need to
tell the ACE scheduler to periodically execute these tasks. This is done by
supplying the following configuration to the `org.apache.ace.scheduler.cfg`
managed service:
+With the synchronisation and repository replication tasks in place, we need to
tell the ACE scheduler to periodically execute these tasks. This is done by
supplying the following configuration to the
<tt>org.apache.ace.scheduler.cfg</tt> managed service:
# execute all LogSyncTasks once every 2 seconds...
org.apache.ace.log.server.task.LogSyncTask=2000
@@ -127,7 +127,7 @@ With the synchronisation and repository
The relay server is now completely configured and ready to serve its targets.
-A complete runnable example can be found in the `run-relay` project of the ACE
source repository. This example project starts a relay server on
`localhost:8282` and expects its upstream server to run at `localhost:8080`. A
list of all required bundles to run a relay server can be found in the
`relay.bndrun` file.
+A complete runnable example can be found in the <tt>run-relay</tt> project of
the ACE source repository. This example project starts a relay server on
<tt>localhost:8282</tt> and expects its upstream server to run at
<tt>localhost:8080</tt> A list of all required bundles to run a relay server
can be found in the <tt>relay.bndrun</tt> file.
## Target configuration
@@ -135,11 +135,11 @@ To only thing that a target needs to kno
-Dagent.discovery.serverurls=http://my.relay.server:8080/
-In fact, the `agent.discovery.serverurls` can take multiple server URLs
(separated by commas) to support a simple form of fail-over, like
`http://first.relay.server:8080/,http://second.relay.server:8080`.
+In fact, the <tt>agent.discovery.serverurls</tt> can take multiple server URLs
(separated by commas) to support a simple form of fail-over, like
<tt>http://first.relay.server:8080/,http://second.relay.server:8080</tt>.
## Notes
-[^1]: this symbolic name *must* be equal to the name used on the upstream
server. By default, the name `auditlog` is used;
+[^1]: this symbolic name *must* be equal to the name used on the upstream
server. By default, the name <tt>auditlog</tt> is used;
[^2]: by convention, use the same name for the endpoint as is used for log
store;
@@ -147,4 +147,4 @@ In fact, the `agent.discovery.serverurls
[^4]: the deployment repository contains all information about the different
deployment packages. Each deployment package is a set of artefacts that can be
installed on a target;
-[^5]: a slave repository is a repository that is not allowed to be changed and
receives its content from another (master) repository.
\ No newline at end of file
+[^5]: a slave repository is a repository that is not allowed to be changed and
receives its content from another (master) repository.
