You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by sv...@apache.org on 2016/09/27 08:46:56 UTC
[1/5] brooklyn-docs git commit: Add config instructions for HTTPS on
Karaf.
Repository: brooklyn-docs
Updated Branches:
refs/heads/master cf63c03d7 -> 7e13af295
Add config instructions for HTTPS on Karaf.
Plus a few more details on key generation.
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/5687acd8
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/5687acd8
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/5687acd8
Branch: refs/heads/master
Commit: 5687acd8f430555a7dec430c628b96862e3366d2
Parents: cceb1b8
Author: Geoff Macartney <ge...@cloudsoftcorp.com>
Authored: Thu Sep 15 17:13:45 2016 +0100
Committer: Geoff Macartney <ge...@cloudsoftcorp.com>
Committed: Thu Sep 15 17:13:45 2016 +0100
----------------------------------------------------------------------
guide/ops/brooklyn_properties.md | 66 +++++++++++++++++++++++++++++------
1 file changed, 56 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5687acd8/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
index 4ab9501..114e4c2 100644
--- a/guide/ops/brooklyn_properties.md
+++ b/guide/ops/brooklyn_properties.md
@@ -213,21 +213,47 @@ or
## HTTPS Configuration
-To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the
-following command:
+### Getting the Certificate
+To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate,
+and add it to a keystore, `keystore.jks`, you can use the following command:
{% highlight bash %}
-% keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key -storepass mypassword -validity 360 -keysize 2048
+% keytool -genkey -keyalg RSA -alias brooklyn \
+ -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword" \
+ -validity 365 -keysize 2048 -keypass "password"
{% endhighlight %}
-You will then be prompted to enter you name and organization details. This will create a keystore with the password `mypassword`
-- you should use your own secure password, which will be the same password used in your brooklyn.properties (below).
-You will also need to replace `<path-to-keystore-directory>` with the full path of the folder where you wish to store your
-keystore.
+Of course, the passwords above should be changed. Omit those arguments above for the tool to prompt you for the values.
-The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server
-name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed
-certificate from a trusted certifying authority should be used instead
+You will then be prompted to enter your name and organization details. This will use (or create, if it does not exist)
+a keystore with the password `mypassword` - you should use your own secure password, which will be the same password
+used in your brooklyn.properties (below). You will also need to replace `<path-to-keystore-directory>` with the full
+path of the folder where you wish to store your keystore. The keystore will contain the newly generated key,
+with alias `brooklyn` and password `password`.
+
+The certificate generated will be a self-signed certificate, which will cause a warning to be displayed by a browser
+when viewing the page. (The various browsers each have ways to import the certificate as a trusted one, for test purposes.)
+
+For production servers, a valid signed certificate from a trusted certifying authority should be used instead.
+Typically keys from a certifying authority are not provided in Java keystore format. To create a Java keystore from
+existing certificates (CA certificate, and public and private keys), you must first create a PKCS12 keystore from them,
+for example with `openssl`; this can then be converted into a Java keystore with `keytool`. For example, with
+a CA certificate `ca.pem`, and public and private keys `cert.pem` and `key.pem`, create the PKCS12 store `server.p12`,
+and then convert it into a keystore `keystore.jks` as follows:
+
+{% highlight bash %}
+% openssl pkcs12 -export -in cert.pem -inkey key.pem \
+ -out server.p12 -name "brooklyn" \
+ -CAfile ca.pem -caname root -chain -passout pass:"password"
+
+% keytool -importkeystore \
+ -deststorepass "password" -destkeypass "password" -destkeystore keystore.jks \
+ -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass "password" \
+ -alias "brooklyn"
+{% endhighlight %}
+
+
+### Configuring HTTPS in Brooklyn
To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
@@ -237,3 +263,23 @@ brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.ke
brooklyn.webconsole.security.keystore.password=mypassword
brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
{% endhighlight %}
+
+### Configuring HTTPS in Brooklyn (Karaf launcher)
+
+In `etc/org.ops4j.pax.web.cfg` in the Brooklyn Karaf distribution root, add:
+
+{% highlight properties %}
+org.osgi.service.http.port.secure=8443
+org.osgi.service.http.secure.enabled=true
+org.ops4j.pax.web.ssl.keystore=./etc/keystores/keystore.jks
+org.ops4j.pax.web.ssl.password=password
+org.ops4j.pax.web.ssl.keypassword=password
+org.ops4j.pax.web.ssl.clientauthwanted=false
+org.ops4j.pax.web.ssl.clientauthneeded=false
+{% endhighlight %}
+
+replacing the passwords with appropriate values, and restart the server. Note the keystore location is relative to
+the installation root, but a fully qualified path can also be given, if it is desired to use some separate pre-existing
+store.
+
+
[2/5] brooklyn-docs git commit: Re-organise for better presentation
in response to review comments.
Posted by sv...@apache.org.
Re-organise for better presentation in response to review comments.
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/073edb1e
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/073edb1e
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/073edb1e
Branch: refs/heads/master
Commit: 073edb1e548b307298c8b0ca6759db2dfe5b0ded
Parents: 5687acd
Author: Geoff Macartney <ge...@cloudsoftcorp.com>
Authored: Fri Sep 16 12:02:00 2016 +0100
Committer: Geoff Macartney <ge...@cloudsoftcorp.com>
Committed: Fri Sep 16 12:02:00 2016 +0100
----------------------------------------------------------------------
guide/index.md | 1 -
guide/misc/osgi.md | 132 ----------------------------------
guide/ops/brooklyn_properties.md | 62 +---------------
guide/ops/https.md | 53 ++++++++++++++
guide/ops/index.md | 2 +
guide/ops/osgi-configuration.md | 118 ++++++++++++++++++++++++++++++
guide/ops/osgi.md | 56 +++++++++++++++
7 files changed, 231 insertions(+), 193 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/index.md
----------------------------------------------------------------------
diff --git a/guide/index.md b/guide/index.md
index 62c52c6..cdb3b46 100644
--- a/guide/index.md
+++ b/guide/index.md
@@ -11,7 +11,6 @@ children:
- { path: /guide/yaml/index.md }
- { path: /guide/java/index.md }
- { path: /guide/ops/index.md }
-- { path: /guide/misc/osgi.md }
- { path: /guide/misc/index.md }
---
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/misc/osgi.md
----------------------------------------------------------------------
diff --git a/guide/misc/osgi.md b/guide/misc/osgi.md
deleted file mode 100644
index dd9ba77..0000000
--- a/guide/misc/osgi.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-title: OSGi Distribution
-layout: website-normal
----
-
-# Running Apache Brooklyn inside Karaf container
-
-The Apache Brooklyn Karaf based distribution lives in brooklyn-server/karaf/apache-brooklyn folder.
-It's still in a testing stage so some features might not work as expected. Do reach out if you
-find any problems.
-
-## Building
-
-{% highlight bash %}
-cd brooklyn-server
-mvn clean install
-cd karaf/apache-brooklyn/target
-tar -zxvf apache-brooklyn-{{ site.brooklyn-version }}.tar.gz
-cd apache-brooklyn-{{ site.brooklyn-version }}
-{% endhighlight %}
-
-## Running
-
-Start the instance using the following command
-
-{% highlight bash %}
-bin/karaf
-{% endhighlight %}
-
-This will launch the [Karaf console](https://karaf.apache.org/manual/latest/users-guide/console.html)
-where you can interact with the running instance. Note that Brooklyn has already started at this point
-and is reachable at the usual web console url.
-
-To start in debug mode use
-
-{% highlight bash %}
-bin/karaf debug
-{% endhighlight %}
-
-and connect to port 5005 using your debugger.
-
-To pause startup until the debugger is connected you can use
-
-{% highlight bash %}
-JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' bin/karaf debug
-{% endhighlight %}
-
-The Karaf container will keep state like installed bundles and configuration between restarts.
-To reset any changes add **clean** to the cli arguments.
-
-## Configuring
-
-To configure the Brooklyn runtime create an **etc/brooklyn.cfg** file, following the standard **brooklyn.properties**
-file format. Values can be viewed and managed dynamically via the OSGI configuration admin commands in Karaf,
-e.g. config:property-set. The global **~/.brooklyn/brooklyn.properties** is still supported and has higher
-priority for duplicate keys, but it's values can't be manipulated with the Karaf commands, so its use is
-discouraged.
-
-You can use the standard ~/.brooklyn/brooklyn.properties file to configure Brooklyn. Alternatively
-create etc/brooklyn.cfg inside the distribution folder (same file format). The keys in the former override
-those in the latter.
-
-Web console related configuration is done through the corresponding Karaf mechanisms:
-
- * The port is set in etc/org.ops4j.pax.web.cfg, key org.osgi.service.http.port.
- * For authentication the JAAS realm "webconsole" is used; by default it will use any
- SecurityProvider implementations configured in Brooklyn falling back to auto generating
- the password. To configure a custom JAAS realm see the jetty.xml file in "brooklyn-server/karaf/jetty-config/src/main/resources"
- and override it by creating a custom one in "etc" folder. Point the "webconsole" login service
- to the JAAS realm you would like to use.
- * For other Jetty related configuration consult the Karaf and pax-web docs.
-
-
-## Catalog in Karaf
-
-
-With the traditional launcher, Brooklyn loads the initial contents of the catalog from a `default.catalog.bom` file
-as described in the section on [installation](/guide/ops/production-installation.html). Brooklyn finds Java
-implementations to provide for certain things in blueprints (entities, enrichers etc.) by scanning the classpath.
-
-In the OSGI world this approach is not used, as each bundle only has visibility of its own and its imported Java packages.
-Instead, in Karaf, each bundle can declare its own `catalog.bom` file, in the root of the bundle,
-with the catalog declarations for any entities etc. that the bundle contains.
-
-For example, the `catalog.bom` file for Brooklyn's Webapp bundle looks like (abbreviated):
-
- brooklyn.catalog:
- version: ...
- items:
- - id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
- itemType: entity
- item:
- type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
- name: Node.JS Application
- ...
- - id: resilient-bash-web-cluster-template
- itemType: template
- name: "Template: Resilient Load-Balanced Bash Web Cluster with Sensors"
- description: |
- Sample YAML to provision a cluster of the bash/python web server nodes,
- with sensors configured, and a load balancer pointing at them,
- and resilience policies for node replacement and scaling
- item:
- name: Resilient Load-Balanced Bash Web Cluster (Brooklyn Example)
-
-In the above YAML the first item declares that the bundle provides an entity whose type is
-`org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService`, and whose name is 'Node.JS Application'. The second
-item declares that the bundle provides a template application, with id `resilient-bash-web-cluster-template`, and
-includes a description for what this is.
-
-## Configuring the applications in the Catalog
-
-When running some particular deployment of Brooklyn it may not be desirable for the sample applications to appear in
-the catalog (for clarity, "application" here in the sense of an item with `itemType: template`).
-For example, if you have developed
-some bundle with your own application and added it to Karaf then you might want only your own application to appear in
-the catalog.
-
-Brooklyn contains a mechanism to allow you to configure what bundles will add their applications to the catalog.
-The Karaf configuration file `/etc/org.apache.brooklyn.core.catalog.bomscanner.cfg` contains two properties,
-one `whitelist` and the other `blacklist`, that bundles must satisfy for their applications to be added to the catalog.
-Each property value is a comma-separated list of regular expressions. The symbolic id of the bundle must match one of
-the regular expressions on the whitelist, and not match any expression on the blacklist, if its applications
-are to be added to the bundle. The default values of these properties are to admit all bundles, and forbid none.
-
-## Caveats
-
-In the OSGi world specifying class names by string in Brooklyn's configuration will work only
-for classes living in Brooklyn's core modules. Raise an issue or ping us on IRC if you find
-a case where this doesn't work for you. For custom SecurityProvider implementations refer to the
-documentation of BrooklynLoginModule.
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
index 114e4c2..aa08875 100644
--- a/guide/ops/brooklyn_properties.md
+++ b/guide/ops/brooklyn_properties.md
@@ -211,49 +211,10 @@ or
{% include java_link.html class_name="EntitlementManager" package_path="org/apache/brooklyn/api/mgmt/entitlement" project_subpath="api" %}.
-## HTTPS Configuration
-### Getting the Certificate
-To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate,
-and add it to a keystore, `keystore.jks`, you can use the following command:
+## Configuring HTTPS in Brooklyn
-{% highlight bash %}
-% keytool -genkey -keyalg RSA -alias brooklyn \
- -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword" \
- -validity 365 -keysize 2048 -keypass "password"
-{% endhighlight %}
-
-Of course, the passwords above should be changed. Omit those arguments above for the tool to prompt you for the values.
-
-You will then be prompted to enter your name and organization details. This will use (or create, if it does not exist)
-a keystore with the password `mypassword` - you should use your own secure password, which will be the same password
-used in your brooklyn.properties (below). You will also need to replace `<path-to-keystore-directory>` with the full
-path of the folder where you wish to store your keystore. The keystore will contain the newly generated key,
-with alias `brooklyn` and password `password`.
-
-The certificate generated will be a self-signed certificate, which will cause a warning to be displayed by a browser
-when viewing the page. (The various browsers each have ways to import the certificate as a trusted one, for test purposes.)
-
-For production servers, a valid signed certificate from a trusted certifying authority should be used instead.
-Typically keys from a certifying authority are not provided in Java keystore format. To create a Java keystore from
-existing certificates (CA certificate, and public and private keys), you must first create a PKCS12 keystore from them,
-for example with `openssl`; this can then be converted into a Java keystore with `keytool`. For example, with
-a CA certificate `ca.pem`, and public and private keys `cert.pem` and `key.pem`, create the PKCS12 store `server.p12`,
-and then convert it into a keystore `keystore.jks` as follows:
-
-{% highlight bash %}
-% openssl pkcs12 -export -in cert.pem -inkey key.pem \
- -out server.p12 -name "brooklyn" \
- -CAfile ca.pem -caname root -chain -passout pass:"password"
-
-% keytool -importkeystore \
- -deststorepass "password" -destkeypass "password" -destkeystore keystore.jks \
- -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass "password" \
- -alias "brooklyn"
-{% endhighlight %}
-
-
-### Configuring HTTPS in Brooklyn
+See [HTTPS Configuration](https.html) for general information on configuring HTTPS.
To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
@@ -264,22 +225,3 @@ brooklyn.webconsole.security.keystore.password=mypassword
brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
{% endhighlight %}
-### Configuring HTTPS in Brooklyn (Karaf launcher)
-
-In `etc/org.ops4j.pax.web.cfg` in the Brooklyn Karaf distribution root, add:
-
-{% highlight properties %}
-org.osgi.service.http.port.secure=8443
-org.osgi.service.http.secure.enabled=true
-org.ops4j.pax.web.ssl.keystore=./etc/keystores/keystore.jks
-org.ops4j.pax.web.ssl.password=password
-org.ops4j.pax.web.ssl.keypassword=password
-org.ops4j.pax.web.ssl.clientauthwanted=false
-org.ops4j.pax.web.ssl.clientauthneeded=false
-{% endhighlight %}
-
-replacing the passwords with appropriate values, and restart the server. Note the keystore location is relative to
-the installation root, but a fully qualified path can also be given, if it is desired to use some separate pre-existing
-store.
-
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/https.md
----------------------------------------------------------------------
diff --git a/guide/ops/https.md b/guide/ops/https.md
new file mode 100644
index 0000000..7bdeacb
--- /dev/null
+++ b/guide/ops/https.md
@@ -0,0 +1,53 @@
+---
+title: HTTPS Configuration
+layout: website-normal
+---
+
+## HTTPS Configuration
+
+### Getting the Certificate
+To enable HTTPS web access, you will need a server certificate in a java keystore. To create a self-signed certificate,
+and add it to a keystore, `keystore.jks`, you can use the following command:
+
+{% highlight bash %}
+% keytool -genkey -keyalg RSA -alias brooklyn \
+ -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword" \
+ -validity 365 -keysize 2048 -keypass "password"
+{% endhighlight %}
+
+Of course, the passwords above should be changed. Omit those arguments above for the tool to prompt you for the values.
+
+You will then be prompted to enter your name and organization details. This will use (or create, if it does not exist)
+a keystore with the password `mypassword` - you should use your own secure password, which will be the same password
+used in your brooklyn.properties (below). You will also need to replace `<path-to-keystore-directory>` with the full
+path of the folder where you wish to store your keystore. The keystore will contain the newly generated key,
+with alias `brooklyn` and password `password`.
+
+The certificate generated will be a self-signed certificate, which will cause a warning to be displayed by a browser
+when viewing the page. (The various browsers each have ways to import the certificate as a trusted one, for test purposes.)
+
+For production servers, a valid signed certificate from a trusted certifying authority should be used instead.
+Typically keys from a certifying authority are not provided in Java keystore format. To create a Java keystore from
+existing certificates (CA certificate, and public and private keys), you must first create a PKCS12 keystore from them,
+for example with `openssl`; this can then be converted into a Java keystore with `keytool`. For example, with
+a CA certificate `ca.pem`, and public and private keys `cert.pem` and `key.pem`, create the PKCS12 store `server.p12`,
+and then convert it into a keystore `keystore.jks` as follows:
+
+{% highlight bash %}
+% openssl pkcs12 -export -in cert.pem -inkey key.pem \
+ -out server.p12 -name "brooklyn" \
+ -CAfile ca.pem -caname root -chain -passout pass:"password"
+
+% keytool -importkeystore \
+ -deststorepass "password" -destkeypass "password" -destkeystore keystore.jks \
+ -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass "password" \
+ -alias "brooklyn"
+{% endhighlight %}
+
+
+### Configuring Brooklyn for HTTPS
+
+How to do this depends on whether you are using the traditional or the Karaf distribution. See either of
+
+* [Traditional Distribution](brooklyn_properties.html#https-configuration)
+* [Karaf Distribution](osgi-configuration.html#https-configuration)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/index.md b/guide/ops/index.md
index a2f154a..e150a5d 100644
--- a/guide/ops/index.md
+++ b/guide/ops/index.md
@@ -13,7 +13,9 @@ children:
- high-availability/
- catalog/
- rest.md
+- osgi.md
- logging.md
+- https.md
- externalized-configuration.md
- requirements.md
- production-installation.md
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/osgi-configuration.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi-configuration.md b/guide/ops/osgi-configuration.md
new file mode 100644
index 0000000..db2a6cd
--- /dev/null
+++ b/guide/ops/osgi-configuration.md
@@ -0,0 +1,118 @@
+---
+title: OSGi Configuration
+layout: website-normal
+---
+
+Configuration of Brooklyn when running under Karaf is largely done through standard Karaf mechanisms.
+The Karaf "Configuration Admin" subsystem is used to manage configuration values loaded at first boot from the
+`.cfg` files in the `etc` directory of the distribution. In the Karaf command line these can then be viewed
+and manipulated by the `config:` commands, see the Karaf documentation for full details.
+
+## Configuring Brooklyn Properties
+
+To configure the Brooklyn runtime create an `etc/brooklyn.cfg` file, following the standard `brooklyn.properties`
+file format. Values can be viewed and managed dynamically via the OSGI configuration admin commands in Karaf,
+e.g. `config:property-set`. The global `~/.brooklyn/brooklyn.properties` is still supported and has higher
+priority for duplicate keys, but it's values can't be manipulated with the Karaf commands, so its use is
+discouraged.
+
+You can use the standard `~/.brooklyn/brooklyn.properties` file to configure Brooklyn. Alternatively
+create `etc/brooklyn.cfg` inside the distribution folder (same file format). The keys in the former override
+those in the latter.
+
+Web console related configuration is done through the corresponding Karaf mechanisms:
+
+ * The port is set in `etc/org.ops4j.pax.web.cfg`, key `org.osgi.service.http.port`.
+ * For authentication the JAAS realm "webconsole" is used; by default it will use any
+ SecurityProvider implementations configured in Brooklyn falling back to auto generating
+ the password. To configure a custom JAAS realm see the `jetty.xml` file in `brooklyn-server/karaf/jetty-config/src/main/resources`
+ and override it by creating a custom one in `etc` folder. Point the "webconsole" login service
+ to the JAAS realm you would like to use.
+ * For other Jetty related configuration consult the Karaf and pax-web docs.
+
+## HTTPS Configuration
+
+See [HTTPS Configuration](https.html) for general information on configuring HTTPS.
+
+In `etc/org.ops4j.pax.web.cfg` in the Brooklyn Karaf distribution root, un-comment the settings:
+
+{% highlight properties %}
+org.osgi.service.http.port.secure=8443
+org.osgi.service.http.secure.enabled=true
+org.ops4j.pax.web.ssl.keystore=${karaf.home}/etc/keystores/keystore.jks
+org.ops4j.pax.web.ssl.password=password
+org.ops4j.pax.web.ssl.keypassword=password
+org.ops4j.pax.web.ssl.clientauthwanted=false
+org.ops4j.pax.web.ssl.clientauthneeded=false
+{% endhighlight %}
+
+replacing the passwords with appropriate values, and restart the server. Note the keystore location is relative to
+the installation root, but a fully qualified path can also be given, if it is desired to use some separate pre-existing
+store.
+
+
+<!--
+----------
+-- NOTE: comment out this section on catalog as the behaviour described is not enabled by default since
+-- https://github.com/apache/brooklyn-server/pull/233; re-enable this when that changes
+----------
+## Catalog in Karaf
+With the traditional launcher, Brooklyn loads the initial contents of the catalog from a `default.catalog.bom` file
+as described in the section on [installation](/guide/ops/production-installation.html). Brooklyn finds Java
+implementations to provide for certain things in blueprints (entities, enrichers etc.) by scanning the classpath.
+
+In the OSGI world this approach is not used, as each bundle only has visibility of its own and its imported Java packages.
+Instead, in Karaf, each bundle can declare its own `catalog.bom` file, in the root of the bundle,
+with the catalog declarations for any entities etc. that the bundle contains.
+
+For example, the `catalog.bom` file for Brooklyn's Webapp bundle looks like (abbreviated):
+
+ brooklyn.catalog:
+ version: ...
+ items:
+ - id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+ itemType: entity
+ item:
+ type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+ name: Node.JS Application
+ ...
+ - id: resilient-bash-web-cluster-template
+ itemType: template
+ name: "Template: Resilient Load-Balanced Bash Web Cluster with Sensors"
+ description: |
+ Sample YAML to provision a cluster of the bash/python web server nodes,
+ with sensors configured, and a load balancer pointing at them,
+ and resilience policies for node replacement and scaling
+ item:
+ name: Resilient Load-Balanced Bash Web Cluster (Brooklyn Example)
+
+In the above YAML the first item declares that the bundle provides an entity whose type is
+`org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService`, and whose name is 'Node.JS Application'. The second
+item declares that the bundle provides a template application, with id `resilient-bash-web-cluster-template`, and
+includes a description for what this is.
+
+## Configuring the applications in the Catalog
+
+When running some particular deployment of Brooklyn it may not be desirable for the sample applications to appear in
+the catalog (for clarity, "application" here in the sense of an item with `itemType: template`).
+For example, if you have developed
+some bundle with your own application and added it to Karaf then you might want only your own application to appear in
+the catalog.
+
+Brooklyn contains a mechanism to allow you to configure what bundles will add their applications to the catalog.
+The Karaf configuration file `/etc/org.apache.brooklyn.core.catalog.bomscanner.cfg` contains two properties,
+one `whitelist` and the other `blacklist`, that bundles must satisfy for their applications to be added to the catalog.
+Each property value is a comma-separated list of regular expressions. The symbolic id of the bundle must match one of
+the regular expressions on the whitelist, and not match any expression on the blacklist, if its applications
+are to be added to the bundle. The default values of these properties are to admit all bundles, and forbid none.
+
+## Caveats
+
+In the OSGi world specifying class names by string in Brooklyn's configuration will work only
+for classes living in Brooklyn's core modules. Raise an issue or ping us on IRC if you find
+a case where this doesn't work for you. For custom SecurityProvider implementations refer to the
+documentation of BrooklynLoginModule.
+
+ END Catalog in Karaf comment -->
+
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/osgi.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi.md b/guide/ops/osgi.md
new file mode 100644
index 0000000..4cb07f2
--- /dev/null
+++ b/guide/ops/osgi.md
@@ -0,0 +1,56 @@
+---
+title: OSGi Distribution
+layout: website-normal
+children:
+- osgi-configuration.md
+---
+
+# Running Apache Brooklyn inside Karaf container
+
+The Apache Brooklyn Karaf based distribution lives in brooklyn-server/karaf/apache-brooklyn folder.
+It's still in a testing stage so some features might not work as expected. Do reach out if you
+find any problems.
+
+## Building
+
+{% highlight bash %}
+cd brooklyn-server
+mvn clean install
+cd karaf/apache-brooklyn/target
+tar -zxvf apache-brooklyn-{{ site.brooklyn-version }}.tar.gz
+cd apache-brooklyn-{{ site.brooklyn-version }}
+{% endhighlight %}
+
+## Running
+
+Start the instance using the following command
+
+{% highlight bash %}
+bin/karaf
+{% endhighlight %}
+
+This will launch the [Karaf console](https://karaf.apache.org/manual/latest/users-guide/console.html)
+where you can interact with the running instance. Note that Brooklyn has already started at this point
+and is reachable at the usual web console url.
+
+To start in debug mode use
+
+{% highlight bash %}
+bin/karaf debug
+{% endhighlight %}
+
+and connect to port 5005 using your debugger.
+
+To pause startup until the debugger is connected you can use
+
+{% highlight bash %}
+JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' bin/karaf debug
+{% endhighlight %}
+
+The Karaf container will keep state like installed bundles and configuration between restarts.
+To reset any changes add **clean** to the cli arguments.
+
+## Configuring
+
+Configuration of Brooklyn when running under Karaf is largely done through standard Karaf mechanisms.
+See the page on [OSGI Configuration](osgi-configuration.html) for details.
\ No newline at end of file
[3/5] brooklyn-docs git commit: Updates from review.
Posted by sv...@apache.org.
Updates from review.
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/cd7d51a6
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/cd7d51a6
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/cd7d51a6
Branch: refs/heads/master
Commit: cd7d51a687680d835796de79c4939124c4c4f928
Parents: 073edb1
Author: Geoff Macartney <ge...@cloudsoftcorp.com>
Authored: Thu Sep 22 10:23:01 2016 +0100
Committer: Geoff Macartney <ge...@cloudsoftcorp.com>
Committed: Thu Sep 22 11:24:45 2016 +0100
----------------------------------------------------------------------
guide/ops/brooklyn_properties.md | 2 +-
guide/ops/https.md | 17 ++++++++---------
guide/ops/osgi-configuration.md | 7 ++++---
guide/ops/osgi.md | 8 ++++----
4 files changed, 17 insertions(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cd7d51a6/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
index aa08875..6d3b5e5 100644
--- a/guide/ops/brooklyn_properties.md
+++ b/guide/ops/brooklyn_properties.md
@@ -212,7 +212,7 @@ or
-## Configuring HTTPS in Brooklyn
+## HTTPS Configuration
See [HTTPS Configuration](https.html) for general information on configuring HTTPS.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cd7d51a6/guide/ops/https.md
----------------------------------------------------------------------
diff --git a/guide/ops/https.md b/guide/ops/https.md
index 7bdeacb..7ed910c 100644
--- a/guide/ops/https.md
+++ b/guide/ops/https.md
@@ -3,11 +3,13 @@ title: HTTPS Configuration
layout: website-normal
---
-## HTTPS Configuration
-
-### Getting the Certificate
+## Getting the Certificate
To enable HTTPS web access, you will need a server certificate in a java keystore. To create a self-signed certificate,
-and add it to a keystore, `keystore.jks`, you can use the following command:
+for testing and non-production use, you can use the tool `keytool` from your Java distribution. (A self-signed
+certificate will cause a warning to be displayed by a browser when viewing the page. The various browsers each have
+ways to import the certificate as a trusted one, for test purposes.)
+
+The following command creates a self-signed certificate and adds it to a keystore, `keystore.jks`:
{% highlight bash %}
% keytool -genkey -keyalg RSA -alias brooklyn \
@@ -15,7 +17,7 @@ and add it to a keystore, `keystore.jks`, you can use the following command:
-validity 365 -keysize 2048 -keypass "password"
{% endhighlight %}
-Of course, the passwords above should be changed. Omit those arguments above for the tool to prompt you for the values.
+The passwords above should be changed to your own values. Omit those arguments above for the tool to prompt you for the values.
You will then be prompted to enter your name and organization details. This will use (or create, if it does not exist)
a keystore with the password `mypassword` - you should use your own secure password, which will be the same password
@@ -23,9 +25,6 @@ used in your brooklyn.properties (below). You will also need to replace `<path-t
path of the folder where you wish to store your keystore. The keystore will contain the newly generated key,
with alias `brooklyn` and password `password`.
-The certificate generated will be a self-signed certificate, which will cause a warning to be displayed by a browser
-when viewing the page. (The various browsers each have ways to import the certificate as a trusted one, for test purposes.)
-
For production servers, a valid signed certificate from a trusted certifying authority should be used instead.
Typically keys from a certifying authority are not provided in Java keystore format. To create a Java keystore from
existing certificates (CA certificate, and public and private keys), you must first create a PKCS12 keystore from them,
@@ -45,7 +44,7 @@ and then convert it into a keystore `keystore.jks` as follows:
{% endhighlight %}
-### Configuring Brooklyn for HTTPS
+## Configuring Brooklyn for HTTPS
How to do this depends on whether you are using the traditional or the Karaf distribution. See either of
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cd7d51a6/guide/ops/osgi-configuration.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi-configuration.md b/guide/ops/osgi-configuration.md
index db2a6cd..2dfa681 100644
--- a/guide/ops/osgi-configuration.md
+++ b/guide/ops/osgi-configuration.md
@@ -3,10 +3,10 @@ title: OSGi Configuration
layout: website-normal
---
-Configuration of Brooklyn when running under Karaf is largely done through standard Karaf mechanisms.
+Configuration of Apache Brooklyn when running under Karaf is largely done through standard Karaf mechanisms.
The Karaf "Configuration Admin" subsystem is used to manage configuration values loaded at first boot from the
`.cfg` files in the `etc` directory of the distribution. In the Karaf command line these can then be viewed
-and manipulated by the `config:` commands, see the Karaf documentation for full details.
+and manipulated by the `config:` commands, see the [Karaf documentation](https://karaf.apache.org/manual/latest/) for full details.
## Configuring Brooklyn Properties
@@ -25,7 +25,8 @@ Web console related configuration is done through the corresponding Karaf mechan
* The port is set in `etc/org.ops4j.pax.web.cfg`, key `org.osgi.service.http.port`.
* For authentication the JAAS realm "webconsole" is used; by default it will use any
SecurityProvider implementations configured in Brooklyn falling back to auto generating
- the password. To configure a custom JAAS realm see the `jetty.xml` file in `brooklyn-server/karaf/jetty-config/src/main/resources`
+ the password. To configure a custom JAAS realm see the `jetty.xml` file in
+ `brooklyn-server/karaf/jetty-config/src/main/resources`
and override it by creating a custom one in `etc` folder. Point the "webconsole" login service
to the JAAS realm you would like to use.
* For other Jetty related configuration consult the Karaf and pax-web docs.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cd7d51a6/guide/ops/osgi.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi.md b/guide/ops/osgi.md
index 4cb07f2..8f765f0 100644
--- a/guide/ops/osgi.md
+++ b/guide/ops/osgi.md
@@ -8,8 +8,8 @@ children:
# Running Apache Brooklyn inside Karaf container
The Apache Brooklyn Karaf based distribution lives in brooklyn-server/karaf/apache-brooklyn folder.
-It's still in a testing stage so some features might not work as expected. Do reach out if you
-find any problems.
+It's still in a testing stage so some features might not work as expected. Please contact us on the
+[mailing list](mailto:dev@brooklyn.apache.org) if you find any problems.
## Building
@@ -39,7 +39,7 @@ To start in debug mode use
bin/karaf debug
{% endhighlight %}
-and connect to port 5005 using your debugger.
+and connect to port 5005 using your normal Java debugger.
To pause startup until the debugger is connected you can use
@@ -47,7 +47,7 @@ To pause startup until the debugger is connected you can use
JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' bin/karaf debug
{% endhighlight %}
-The Karaf container will keep state like installed bundles and configuration between restarts.
+The Karaf container will keep state such as installed bundles and configuration between restarts.
To reset any changes add **clean** to the cli arguments.
## Configuring
[4/5] brooklyn-docs git commit: Add bin/start instruction.
Posted by sv...@apache.org.
Add bin/start instruction.
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/621c074e
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/621c074e
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/621c074e
Branch: refs/heads/master
Commit: 621c074eef017c0086a70ea3bc48f72b7cbe794b
Parents: cd7d51a
Author: Geoff Macartney <ge...@cloudsoftcorp.com>
Authored: Thu Sep 22 11:41:01 2016 +0100
Committer: Geoff Macartney <ge...@cloudsoftcorp.com>
Committed: Thu Sep 22 11:41:01 2016 +0100
----------------------------------------------------------------------
guide/ops/osgi.md | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/621c074e/guide/ops/osgi.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi.md b/guide/ops/osgi.md
index 8f765f0..e8058a1 100644
--- a/guide/ops/osgi.md
+++ b/guide/ops/osgi.md
@@ -23,7 +23,7 @@ cd apache-brooklyn-{{ site.brooklyn-version }}
## Running
-Start the instance using the following command
+Start the instance with a console in the foreground using the following command
{% highlight bash %}
bin/karaf
@@ -47,6 +47,13 @@ To pause startup until the debugger is connected you can use
JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' bin/karaf debug
{% endhighlight %}
+
+Start the instance as a server in the background using the following command
+
+{% highlight bash %}
+bin/start
+{% endhighlight %}
+
The Karaf container will keep state such as installed bundles and configuration between restarts.
To reset any changes add **clean** to the cli arguments.
[5/5] brooklyn-docs git commit: Closes #108
Posted by sv...@apache.org.
Closes #108
Add config instructions for HTTPS on Karaf.
Plus a few more details on key generation.
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/7e13af29
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/7e13af29
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/7e13af29
Branch: refs/heads/master
Commit: 7e13af295265c4e2bac04a1b7fb5a2a35e2c8d98
Parents: cf63c03 621c074
Author: Svetoslav Neykov <sv...@cloudsoftcorp.com>
Authored: Tue Sep 27 11:46:45 2016 +0300
Committer: Svetoslav Neykov <sv...@cloudsoftcorp.com>
Committed: Tue Sep 27 11:46:45 2016 +0300
----------------------------------------------------------------------
guide/index.md | 1 -
guide/misc/osgi.md | 132 ----------------------------------
guide/ops/brooklyn_properties.md | 18 +----
guide/ops/https.md | 52 ++++++++++++++
guide/ops/index.md | 2 +
guide/ops/osgi-configuration.md | 119 ++++++++++++++++++++++++++++++
guide/ops/osgi.md | 63 ++++++++++++++++
7 files changed, 239 insertions(+), 148 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7e13af29/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------