felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Apache Felix Web Console
Date Mon, 19 Dec 2011 09:20:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Web+Console">Apache
Felix Web Console</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >| {{felix.webconsole.locale}} | {{locale}}
| <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Please note that setting any of
these properties as framework property makes them visible to all bundles deployed. This is
particularly to be considered in case of the {{felix.webconsole.password}} property (as for
authentication, the use of a <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{{WebConsoleSecurityProvider}}</span>
<span class="diff-added-words"style="background-color: #dfd;">[Web Console Security
Provider]</span> is suggested anyway). <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h4. Configuration of the
OSGi Http Service <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p><a name="ApacheFelixWebConsole-top"></a></p>

<h1><a name="ApacheFelixWebConsole-ApacheFelixWebConsole"></a>Apache Felix
Web Console</h1>

<div><a href='#ApacheFelixWebConsole-Requirements'>Requirements</a> | <a
href='#ApacheFelixWebConsole-Variants'>Variants</a> | <a href='#ApacheFelixWebConsole-Installation'>Installation</a>
| <a href='#ApacheFelixWebConsole-Configuration'>Configuration</a> | <a href='#ApacheFelixWebConsole-Security'>Security</a>
| <a href='#ApacheFelixWebConsole-BrowserCompliance'>Browser Compliance</a> |
<a href='#ApacheFelixWebConsole-ExtendingtheWebConsole'>Extending the Web Console</a>
| <a href='#ApacheFelixWebConsole-RESTfulAPI'>RESTful API</a> | <a href='#ApacheFelixWebConsole-Issues'>Issues</a>
| <a href='#ApacheFelixWebConsole-Screenshots'>Screenshots</a></div>

<p>The Apache Felix Web Console is a simple tool to inspect and manage OSGi framework
instances using your favourite Web Browser.</p>


<h2><a name="ApacheFelixWebConsole-Requirements"></a>Requirements</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>The Web Console only has a single required dependency on the framework: A running
implementation of the OSGi Http Service Specification. The reason for this is, that the Web
Console is implemented as a servlet (actually just a gateway servlet dispatching to Web Console
plugins) which is registered with the Http Service. If your framework does not yet have a
Http Service installed, you might select from a variety of such implementations. The following
is just an incomplete list:</p>

<ul>
	<li>Apache Felix HTTP Service. This is a very basic implementation of the OSGi Http
Service based on Jetty 6.1.7. The Apache Felix HTTP Service has not been released yet, so
you would have to build it yourself.</li>
	<li>PAX Web Service. The PAX Web Service is the basis for a whole range of additions
from the <a href="http://www.ops4j.org" class="external-link" rel="nofollow">OPS4J</a>
project. The PAX Web Service is also based on Jetty 6 and may be dowloaded from the <a
href="http://wiki.ops4j.org/confluence/display/ops4j/Pax+Web" class="external-link" rel="nofollow">OPS4J
PAX Web</a> page.</li>
	<li>Equinox HTTP Service implementation. You can get more information on the Equinox
implementation from the <a href="http://www.eclipse.org/equinox/server/" class="external-link"
rel="nofollow">Server-Side Equinox</a> page.</li>
</ul>



<p>Apart from that Web Console has the following dependencies, which do not need to
be satisfied. In this case the respective functionality is just missing.</p>

<ul>
	<li>OSGi Log Service &#8211; The Log Service is used for logging. If the service
is not available the Web Console prints logging to the standard output</li>
	<li>OSGi Configuration Admin Service and OSGi Metatype Service &#8211; The Configuration
Admin and Metatype services are used to support simple form based configuration administration</li>
	<li>Apache Felix Declarative Services &#8211; If your framework uses the Apache
Felix Declarative Services implementation, you can use to the Web Console to inspect the declared
components available from the various bundles and managed by the Service Component Runtime.</li>
</ul>



<p>Note, that the Apache Felix Declarative Services implementation is the only Apache
Felix dependency contained in the Web Console. If you do not use the Apache Felix Declarative
Services implementation, you just cannot inspect the declared components (because there is
no official public API for this). Otherwise the Web Console perfectly operates without any
problems.</p>



<h2><a name="ApacheFelixWebConsole-Variants"></a>Variants</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>The Web Console Bundle is available in two variants: A <em>full</em>
variant and a <em>bare</em> variant. The <em>full</em> variant embeds
three Java libraries which are not embedded in the <em>bare</em> variant. The
<em>bare</em> variant expects the packages provided by those libraries to be exported
from bundles installed in the framework.</p>

<p>The three libraries are :</p>

<ul>
	<li>Apache Commons IO</li>
	<li>Apache Commons FileUpload</li>
	<li>JSON</li>
</ul>


<p>Version 2.0.6 is the first release providing a <em>bare</em> variant.
In this release both variants have the same symbolic name but a different file name: <tt>org.apache.felix.webconsole-2.0.6.jar</tt>
for the <em>full</em> variant and <tt>org.apache.felix.webconsole-2.0.6-bare.jar</tt>
for the <em>bare</em> variant. This is <a href="https://issues.apache.org/jira/browse/FELIX-2086"
class="external-link" rel="nofollow">considered a bug</a> and will be fixed in the
next release as follows:</p>

<ul>
	<li><em>Full</em> variant symbolic name: <tt>org.apache.felix.webconsole</tt></li>
	<li><em>Bare</em> variant symbolic name: <tt>org.apache.felix.webconsole.bare</tt></li>
</ul>



<h2><a name="ApacheFelixWebConsole-Installation"></a>Installation</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>To install just use your favourite current means of installing new bundles in to
the OSGi framework. For example using the Apache Felix shell console you might do:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>&gt; install http://mirror.switch.ch/mirror/apache/dist/felix/org.apache.felix.webconsole-2.0.6.jar
bundle x
&gt; start x
</pre>
</div></div>

<p>where <em>x</em> is the bundle number printed by the Shell Console indicating
the Bundle ID of the Web Console bundle.</p>


<h2><a name="ApacheFelixWebConsole-Configuration"></a>Configuration</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>The configuration of the Web Console consists of two parts: One part is the configuration
of the Http Service defining at which host address (host and port number) the servlet container
is accessible. This configuration is technically outside of the scope of the Web Console configuration.
See below for more information and how this is influenced.</p>

<p>The second part of the Web Console configuration is the configuration of the console
itself. The Web Console is configured using the OSGi Configuration Admin Service in that the
Web Console registered a <tt>ManagedService</tt> with Service PID <tt>org.apache.felix.webconsole.internal.servlet.OsgiManager</tt>
(of course you may well use the Web Console to edit the configuration of the Web Console itself).</p>

<p>The Web Console supports the following settings with their corresponding default
values:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>manager.root</tt> </td>
<td class='confluenceTd'> <tt>/system/console</tt> </td>
<td class='confluenceTd'> The root path to the OSGi Management Console. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>default.render</tt> </td>
<td class='confluenceTd'> <tt>bundles</tt> </td>
<td class='confluenceTd'> The name of the default configuration page  when invoking
the OSGi Management console. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>realm</tt> </td>
<td class='confluenceTd'> <tt>OSGi Management Console</tt> </td>
<td class='confluenceTd'> The name of the HTTP Authentication Realm. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>username</tt> </td>
<td class='confluenceTd'> <tt>admin</tt> </td>
<td class='confluenceTd'> The name of the user allowed to access the OSGi Management
Console. To disable authentication clear this value. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>password</tt> </td>
<td class='confluenceTd'> <tt>admin</tt> </td>
<td class='confluenceTd'> The password for the user allowed to access the OSGi Management
Console. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>plugins</tt> </td>
<td class='confluenceTd'> all plugins enabled </td>
<td class='confluenceTd'> The labels of the plugins enabled and displayed. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>loglevel</tt> </td>
<td class='confluenceTd'> <tt>2</tt> </td>
<td class='confluenceTd'> Log level filter for the <tt>AbstractWebConsole</tt>
log methods. This is an integer value matching the levels defined by the OSGi Log Service.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>locale</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> If set, this locale forces the localization to use this locale
instead of the one requested by the web browser. </td>
</tr>
</tbody></table>
</div>


<p>The default values apply if the respective property is missing from the configuration
or if no configuration is provided at all.</p>


<h4><a name="ApacheFelixWebConsole-FrameworkProperties"></a>Framework Properties</h4>

<p>Some of the configuration properties supported through the OSGi Configuration Admin
service can also be set globally and statically as framework properties. Such framework properties
will also be considered actual default values for missing properties in Configuration Admin
configuration as well as for the Metatype descriptor.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Framework Property </th>
<th class='confluenceTh'> Configuration Admin Property </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>felix.webconsole.manager.root</tt> </td>
<td class='confluenceTd'> <tt>manager.root</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>felix.webconsole.realm</tt> </td>
<td class='confluenceTd'> <tt>realm</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>felix.webconsole.username</tt> </td>
<td class='confluenceTd'> <tt>username</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>felix.webconsole.password</tt> </td>
<td class='confluenceTd'> <tt>password</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>felix.webconsole.loglevel</tt> </td>
<td class='confluenceTd'> <tt>loglevel</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>felix.webconsole.locale</tt> </td>
<td class='confluenceTd'> <tt>locale</tt> </td>
</tr>
</tbody></table>
</div>


<p>Please note that setting any of these properties as framework property makes them
visible to all bundles deployed. This is particularly to be considered in case of the <tt>felix.webconsole.password</tt>
property (as for authentication, the use of a <a href="/confluence/display/FELIX/Web+Console+Security+Provider"
title="Web Console Security Provider">Web Console Security Provider</a> is suggested
anyway).</p>

<h4><a name="ApacheFelixWebConsole-ConfigurationoftheOSGiHttpService"></a>Configuration
of the OSGi Http Service</h4>

<p>As said above, the configuration of the OSGi Http Service used by the Web Console
to register itself is outside of the scope of the Web Console. Lets just say, the OSGi Http
Service specification defines a system propety &#8211; <tt>org.osgi.service.http.port</tt>
&#8211; which may be set to define the port at which the Http Service should listen for
HTTP requests. The respective Http Service implementation may define additional properties
to define the actual interface on which to listen or to define a servlet context path.</p>

<p>By default it is probably safe to assume, that having set the <tt>org.osgi.service.http.port</tt>
to a defined value, the Http Service implementation will listen on all interfaces for requests
at the set port number and that no servlet context path actually exists. For example, given
the <tt>org.osgi.service.http.port</tt> property is set to <em>8888</em>
the Web Console in the local system can be reached at : <tt><a href="http://localhost:8888/system/console"
class="external-link" rel="nofollow">http://localhost:8888/system/console</a></tt>,
where the <tt>/system/console</tt> path is configured using the <tt>manager.root</tt>
configuration property (see the Configuration section).</p>

<p>If you happen to deploy an OSGi framework instance inside a traditional web application
and thus the Http Service implementation is actually a bridge into the existing servlet container
(see for example <a href="http://www.eclipse.org/equinox/server/http_in_container.php"
class="external-link" rel="nofollow">Equinox in a Servlet Container</a> or the Apache
Sling Launchpad Web application), the host, port and context path are defined by your servlet
container and web application deployment. For example, if the servlet container listens on
host <tt>sample.org</tt> at port <tt>8888</tt> and the web application
with your OSGi container is available in the <tt>/osgi</tt> context, the Web Console
would be accessible at <tt><a href="http://sample.org:8888/osgi/system/console" class="external-link"
rel="nofollow">http://sample.org:8888/osgi/system/console</a></tt>.</p>


<h2><a name="ApacheFelixWebConsole-Security"></a>Security</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>The Web Console only has very basic security at the moment supporting only HTTP Basic
authentication. This security is enabled by default and may be disabled by simply clearing
the <tt>username</tt> property.</p>

<p>To enhance the security of the Web Console you strongly encouraged to change at least
the <tt>password</tt> for the admin user.</p>

<p>As of Web Console 3.1.0 this simple user setup can be extended by providing <a
href="/confluence/display/FELIX/Web+Console+Security+Provider" title="Web Console Security
Provider">Web Console Security Provider</a>. See that page for more information.</p>


<h2><a name="ApacheFelixWebConsole-BrowserCompliance"></a>Browser Compliance</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>The goal of the Web Console is to support as big a range of Web Browsers as possible.
As it stands now, Firefox (versions 2 and 3), Opera and Internet Explorer (versions 6 and
7) seem to be capable of using the Web Console. Should you encounter any problems with your
particular browser, please report an issue for the <em>Web Console</em> in our
issue tracking system (<a href="https://issues.apache.org/jira/browse/Felix" class="external-link"
rel="nofollow">JIRA</a>).</p>

<p>Beginning with Release 1.2.8 the Web Console is using JQuery to enhance the user
experience. This should also help in keeping browser support on the broadest possible basis.</p>


<h2><a name="ApacheFelixWebConsole-ExtendingtheWebConsole"></a>Extending
the Web Console</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>The Web Console can be extended by registering an OSGi service for the interface
<tt>javax.servlet.Servlet</tt> with the service property <tt>felix.webconsole.label</tt>
set to the label (last segment in the URL) of the page. The respective service is called a
Web Console Plugin or a plugin for short.</p>

<p>Please for to the <a href="/confluence/display/FELIX/Extending+the+Apache+Felix+Web+Console"
title="Extending the Apache Felix Web Console">Extending the Apache Felix Web Console</a>
for full documentation on extending the Apache Felix Web Console.</p>


<h2><a name="ApacheFelixWebConsole-RESTfulAPI"></a>RESTful API</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>While the Web Console does not have a full featured and documented REST-ful API,
most plugins try to follow REST approaches. For example the Bundles plugin is able to send
information on all bundles or a single directly addressed bundle.</p>

<p>An attempt is made to document the current state of REST-like APIs at <a href="/confluence/display/FELIX/Web+Console+RESTful+API"
title="Web Console RESTful API">Web Console RESTful API</a></p>


<h2><a name="ApacheFelixWebConsole-Issues"></a>Issues</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<p>Should you have any questions using the Web Console, please send a note to one of
our <a href="/confluence/display/FELIX/mailinglists" title="mailinglists">Mailing Lists</a>.</p>

<p>Please report any issues with the Web Console in our issue tracking system (<a
href="https://issues.apache.org/jira/browse/Felix" class="external-link" rel="nofollow">JIRA</a>)
and be sure to report for the <em>Web Console</em> component. See our <a href="/confluence/display/FELIX/Issue+Tracking"
title="Issue Tracking">Issue Tracking</a> page for more details.</p>


<h2><a name="ApacheFelixWebConsole-Screenshots"></a>Screenshots</h2>
<p><a href="#ApacheFelixWebConsole-top">Top</a></p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <span class="image-wrap" style=""><a class="confluence-thumbnail-link
1274x826" href='https://cwiki.apache.org/confluence/download/attachments/95821/console-bundles.png'><img
src="/confluence/download/thumbnails/95821/console-bundles.png" title="Bundle List" style="border:
0px solid black" /></a></span> </td>
<td class='confluenceTd'> <span class="image-wrap" style=""><a class="confluence-thumbnail-link
1274x826" href='https://cwiki.apache.org/confluence/download/attachments/95821/console-bundles-details.png'><img
src="/confluence/download/thumbnails/95821/console-bundles-details.png" title="Bundle Details"
style="border: 0px solid black" /></a></span> </td>
<td class='confluenceTd'> <span class="image-wrap" style=""><a class="confluence-thumbnail-link
1274x826" href='https://cwiki.apache.org/confluence/download/attachments/95821/console-components.png'><img
src="/confluence/download/thumbnails/95821/console-components.png" title="Declarative Services
Components (requires Apache Felix SCR)" style="border: 0px solid black" /></a></span>
</td>
</tr>
<tr>
<td class='confluenceTd'> Bundle List </td>
<td class='confluenceTd'> Bundle Details </td>
<td class='confluenceTd'> Declarative Services Components (requires Apache Felix SCR)
</td>
</tr>
<tr>
<td class='confluenceTd'> <span class="image-wrap" style=""><a class="confluence-thumbnail-link
1274x826" href='https://cwiki.apache.org/confluence/download/attachments/95821/console-config.png'><img
src="/confluence/download/thumbnails/95821/console-config.png" title="Configuration Admin"
style="border: 0px solid black" /></a></span> </td>
<td class='confluenceTd'> <span class="image-wrap" style=""><a class="confluence-thumbnail-link
1468x1136" href='https://cwiki.apache.org/confluence/download/attachments/95821/console-status.png'><img
src="/confluence/download/thumbnails/95821/console-status.png" title="System Status: Bundles,
Configuration, Services, Properties, ..." style="border: 0px solid black" /></a></span>
</td>
<td class='confluenceTd'> <span class="image-wrap" style=""><a class="confluence-thumbnail-link
1274x826" href='https://cwiki.apache.org/confluence/download/attachments/95821/console-system-info.png'><img
src="/confluence/download/thumbnails/95821/console-system-info.png" title="System Information"
style="border: 0px solid black" /></a></span> </td>
</tr>
<tr>
<td class='confluenceTd'> Configuration Admin </td>
<td class='confluenceTd'> System Status </td>
<td class='confluenceTd'> System Information </td>
</tr>
</tbody></table>
</div>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Web+Console">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=95821&revisedVersion=25&originalVersion=24">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Web+Console?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message