Update to Karaf as default
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/e73b66e0 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/e73b66e0 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/e73b66e0 Branch: refs/heads/0.12.0 Commit: e73b66e0f995008b8a223a37a367eb5ac2650f36 Parents: d777a7d Author: Duncan Godwin <[email protected]> Authored: Fri Sep 8 16:46:26 2017 +0100 Committer: Duncan Godwin <[email protected]> Committed: Tue Sep 26 15:24:16 2017 +0100 ---------------------------------------------------------------------- contributing/inline-children.md | 2 +- guide/blueprints/java/entitlements.md | 2 +- .../concepts/configuration-sensor-effectors.md | 16 +- guide/ops/brooklyn_properties.md | 225 ------------------- guide/ops/cli/cli-ref-guide.md | 2 +- guide/ops/configuration/brooklyn_cfg.md | 215 ++++++++++++++++++ guide/ops/configuration/cors.md | 45 ++++ guide/ops/configuration/https.md | 52 +++++ guide/ops/configuration/index.md | 50 +++++ guide/ops/configuration/osgi-configuration.md | 119 ++++++++++ guide/ops/externalized-configuration.md | 28 +-- guide/ops/gui/running.md | 4 +- .../high-availability-supplemental.md | 33 ++- guide/ops/high-availability/index.md | 18 +- guide/ops/https.md | 52 ----- guide/ops/index.md | 4 +- guide/ops/osgi-configuration.md | 119 ---------- guide/ops/osgi.md | 71 ------ guide/ops/paths.md | 49 ++++ guide/ops/persistence/index.md | 223 ++++-------------- guide/ops/production-installation.md | 14 +- guide/ops/security-guidelines.md | 2 +- guide/ops/server-cli-reference.md | 6 +- guide/ops/starting-stopping-monitoring.md | 14 +- guide/start/blueprints.md | 2 +- guide/start/brooklyn.properties | 12 +- guide/start/running.md | 14 +- 27 files changed, 664 insertions(+), 729 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/contributing/inline-children.md ---------------------------------------------------------------------- diff --git a/contributing/inline-children.md b/contributing/inline-children.md index e16def5..fb5f887 100644 --- a/contributing/inline-children.md +++ b/contributing/inline-children.md @@ -46,7 +46,7 @@ Brooklyn supports a wide range of locations: specifying already-existing hosts to use * And many others, including object stores and online services -Configuration can be set in `~/.brooklyn/brooklyn.properties` +Configuration can be set in `brooklyn.cfg` or directly in YAML when specifying a location. On some entities, config keys determining matching selection and provisioning behavior can also be set in `provisioning.properties`. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/blueprints/java/entitlements.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/java/entitlements.md b/guide/blueprints/java/entitlements.md index 59de4aa..91d8dac 100644 --- a/guide/blueprints/java/entitlements.md +++ b/guide/blueprints/java/entitlements.md @@ -31,7 +31,7 @@ which you can see [here]({{ site.brooklyn.url.git }}/core/src/test/java/org/apac and include in your project by adding the core tests JAR to your `dropins` folder. There are some entitlements schemes which exist out of the box, so for a simpler setup, -see [Operations: Entitlements]({{ site.path.guide }}/ops/brooklyn_properties.html#entitlements). +see [Operations: Entitlements]({{ site.path.guide }}/ops/configuration/brooklyn_cfg.html#entitlements). There are also more complex schemes which some users have developed, including LDAP extensions which re-use the LDAP authorization support in Brooklyn, http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/concepts/configuration-sensor-effectors.md ---------------------------------------------------------------------- diff --git a/guide/concepts/configuration-sensor-effectors.md b/guide/concepts/configuration-sensor-effectors.md index 6363b8a..3575337 100644 --- a/guide/concepts/configuration-sensor-effectors.md +++ b/guide/concepts/configuration-sensor-effectors.md @@ -7,34 +7,34 @@ categories: [use, guide, defining-applications] ### Configuration -All entities contain a map of config information. This can contain arbitrary values, typically keyed under static ``ConfigKey`` fields on the ``Entity`` sub-class. These values are inherited, so setting a configuration value at the +All entities contain a map of config information. This can contain arbitrary values, typically keyed under static `ConfigKey` fields on the `Entity` sub-class. These values are inherited, so setting a configuration value at the application level will make it available in all entities underneath unless it is overridden. -Configuration is propagated when an application "goes live" (i.e. it becomes "managed", either explicitly or when its ``start()`` method is invoked), so config values must be set before this occurs. +Configuration is propagated when an application "goes live" (i.e. it becomes "managed", either explicitly or when its `start()` method is invoked), so config values must be set before this occurs. -Configuration values can be specified in a configuration file (``~/.brooklyn/brooklyn.properties``) +Configuration values can be specified in a configuration file (`brooklyn.cfg`) to apply universally, and/or programmatically to a specific entity and its descendants by calling `.configure(KEY, VALUE)` in the entity spec when creating it. -There is also an ``entity.config().set(KEY, VALUE)`` method. +There is also an `entity.config().set(KEY, VALUE)` method. Additionally, many common configuration parameters are available as "flags" which can be supplied as Strings when constructing then entity, in the form -``EntitySpec.createË(MyEntity.class).configure("config1", "value1").configure("config2", "value2")``. +`EntitySpec.createË(MyEntity.class).configure("config1", "value1").configure("config2", "value2")`. Documentation of the flags available for individual entities can normally be found in the javadocs. -The ``@SetFromFlag`` annotations on ``ConfigKey`` static field definitions +The `@SetFromFlag` annotations on `ConfigKey` static field definitions in the entity's interface is the recommended mechanism for exposing configuration options. ### Sensors and Effectors -***Sensors*** (activity information and notifications) and ***effectors*** (operations that can be invoked on the entity) are defined by entities as static fields on the ``Entity`` subclass. +***Sensors*** (activity information and notifications) and ***effectors*** (operations that can be invoked on the entity) are defined by entities as static fields on the `Entity` subclass. Sensors can be updated by the entity or associated tasks, and sensors from an entity can be subscribed to by its parent or other entities to track changes in an entity's activity. Effectors can be invoked by an entity's parent remotely, and the invoker is able to track the execution of that effector. Effectors can be invoked by other entities, but use this functionality with care to prevent too many managers! An entity consists of a Java interface (used when interacting with the entity) and a Java class. For resilience. it is recommended to store -the entity's state in attributes (see ``getAttribute(AttributeKey)``). If internal fields can be used then the data will be lost on brooklyn +the entity's state in attributes (see `getAttribute(AttributeKey)`). If internal fields can be used then the data will be lost on brooklyn restart, and may cause problems if the entity is to be moved to a different brooklyn management node. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/brooklyn_properties.md ---------------------------------------------------------------------- diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md deleted file mode 100644 index 422c10e..0000000 --- a/guide/ops/brooklyn_properties.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: brooklyn.properties -layout: website-normal -children: -- { section: Quick Setup } -- { section: Locations } -- { section: Java } -- { section: Authentication } -- { section: Entitlements } -- { section: HTTPS Configuration } ---- - -{% include fields.md %} - -The file `~/.brooklyn/brooklyn.properties` is read when Brooklyn starts -to load server configuration values. - -A template [brooklyn.properties]({{brooklyn_properties_url_path}}) file is available, -with abundant comments. - - -## Quick Setup - -The most common properties set in this file are for access control. Without this, Brooklyn's -web-console and REST api will require no authentication. - -The simplest way to specify users and passwords is shown below (but see the -[Authentication](#authentication) section for how to avoid storing passwords in plain text): - -{% highlight properties %} -brooklyn.webconsole.security.users=admin,bob -brooklyn.webconsole.security.user.admin.password=AdminPassw0rd -brooklyn.webconsole.security.user.bob.password=BobPassw0rd -{% endhighlight %} - -The properties file *must* have permissions 600 -(i.e. readable and writable only by the file's owner), -for some security. - -In many cases, it is preferable instead to use an external credentials store such as LDAP. -Information on configuring these is [below](#authentication). - -If coming over a network it is highly recommended additionally to use `https`. -This can be configured with: - -{% highlight properties %} -brooklyn.webconsole.security.https.required=true -{% endhighlight %} - -More information, including setting up a certificate, is described [further below](#https-configuration). - - -## Camp YAML Expressions - -Values in `brooklyn.properties` can use the Camp YAML syntax. Any value starting `$brooklyn:` is -parsed as a Camp YAML expression. - -This allows [externalized configuration]({{ site.path.guide}}/ops/externalized-configuration.html) to be used from -brooklyn.properties. For example: - -{% highlight properties %} -brooklyn.location.jclouds.aws-ec2.identity=$brooklyn:external("vault", "aws-identity") -brooklyn.location.jclouds.aws-ec2.credential=$brooklyn:external("vault", "aws-credential") -{% endhighlight %} - -If for some reason one requires a literal value that really does start with `$brooklyn:` (i.e. -for the value to not be parsed), then this can be achieved by using the syntax below. This -example returns the property value `$brooklyn:myexample`: - -{% highlight properties %} -example.property=$brooklyn:literal("$brooklyn:myexample") -{% endhighlight %} - - -## Locations - -Information on defining locations in the `brooklyn.properties` file is available [here]({{ site.path.guide }}/locations/). - - -## Java - -Arbitrary data can be set in the `brooklyn.properties`. -This can be accessed in java using `ManagementContext.getConfig(KEY)`. - - -## Authentication - -**Security Providers** are the mechanism by which different authentication authorities are plugged in to Brooklyn. -These can be configured by specifying `brooklyn.webconsole.security.provider` equal -to the name of a class implementing `SecurityProvider`. -An implementation of this could point to Spring, LDAP, OpenID or another identity management system. - -The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords -which should be specified as configuration parameters e.g. in `brooklyn.properties`. -This configuration could look like: - -{% highlight properties %} -brooklyn.webconsole.security.users=admin -brooklyn.webconsole.security.user.admin.salt=OHDf -brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 -{% endhighlight %} - -The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users. - -To generate this, the brooklyn CLI can be used: - -{% highlight bash %} -brooklyn generate-password --user admin - -Enter password: -Re-enter password: - -Please add the following to your brooklyn.properies: - -brooklyn.webconsole.security.users=admin -brooklyn.webconsole.security.user.admin.salt=OHDf -brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 -{% endhighlight %} - -Alternatively, in dev/test environments where a lower level of security is required, -the syntax `brooklyn.webconsole.security.user.<username>=<password>` can be used for -each `<username>` specified in the `brooklyn.webconsole.security.users` list. - -Other security providers available include: - -### No one - -`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.BlackholeSecurityProvider` -will block all logins (e.g. if not using the web console) - -### No security - -`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.AnyoneSecurityProvider` -will allow logins with no credentials (e.g. in secure dev/test environments) - -### LDAP - -`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.LdapSecurityProvider` -will cause Brooklyn to call to an LDAP server to authenticate users; -The other things you need to set in `brooklyn.properties` are: - -* `brooklyn.webconsole.security.ldap.url` - ldap connection url -* `brooklyn.webconsole.security.ldap.realm` - ldap dc parameter (domain) -* `brooklyn.webconsole.security.ldap.ou` *optional, by default it set to Users* - ldap ou parameter - -**brooklyn.properties example configuration:** - -~~~ -brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.LdapSecurityProvider -brooklyn.webconsole.security.ldap.url=ldap://localhost:10389/????X-BIND-USER=uid=admin%2cou=system,X-BIND-PASSWORD=secret,X-COUNT-LIMIT=1000 -brooklyn.webconsole.security.ldap.realm=example.com -~~~ - -After you setup the brooklyn connection to your LDAP server, you can authenticate in brooklyn using your cn (e.g. John Smith) and your password. -`org.apache.brooklyn.rest.security.provider.LdapSecurityProvider` searches in the LDAP tree in LDAP://cn=John Smith,ou=Users,dc=example,dc=com - -If you want to customize the ldap path or something else which is particular to your LDAP setup you -can extend `LdapSecurityProvider` class or implement from scratch the `SecurityProvider` interface. - - -## Entitlements - -In addition to login access, fine-grained permissions -- including -seeing entities, creating applications, seeing sensors, and invoking effectors -- -can be defined on a per-user *and* per-target (e.g. which entity/effector) basis -using a plug-in **Entitlement Manager**. - -This can be set globally with the property: - -{% highlight properties %} -brooklyn.entitlements.global=<class> -{% endhighlight %} - -The default entitlement manager is one which responds to per-user entitlement rules, -and understands: - -* `root`: full access, including to the Groovy console -* `user`: access to everything but actions that affect the server itself. Such actions include the - Groovy console, stopping the server and retrieving management context configuration. -* `readonly`: read-only access to almost all information -* `minimal`: access only to server stats, for use by monitoring systems - -These keywords are also understood at the `global` level, so to grant full access to `admin`, -read-only access to `support`, limited access to `metrics` and regular access to `user` -you can write: - -{% highlight properties %} -brooklyn.entitlements.global=user -brooklyn.entitlements.perUser.admin=root -brooklyn.entitlements.perUser.support=readonly -brooklyn.entitlements.perUser.metrics=minimal -{% endhighlight %} - -Under the covers this invokes the `PerUserEntitlementManager`, -with a `default` set (and if not specified `default` defaults to `minimal`); -so the above can equivalently be written: - -{% highlight properties %} -brooklyn.entitlements.global=org.apache.brooklyn.core.mgmt.entitlement.PerUserEntitlementManager -brooklyn.entitlements.perUser.default=user -brooklyn.entitlements.perUser.admin=root -brooklyn.entitlements.perUser.support=readonly -brooklyn.entitlements.perUser.metrics=minimal -{% endhighlight %} - -For more information, see -[Java: Entitlements]({{ site.path.guide }}/blueprints/java/entitlements.html). -or -{% include java_link.html class_name="EntitlementManager" package_path="org/apache/brooklyn/api/mgmt/entitlement" project_subpath="api" %}. - - - -## HTTPS Configuration - -See [HTTPS Configuration](https.html) for general information on configuring HTTPS. - -To enable HTTPS in Brooklyn, add the following to your brooklyn.properties: - -{% highlight properties %} -brooklyn.webconsole.security.https.required=true -brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key -brooklyn.webconsole.security.keystore.password=mypassword -brooklyn.webconsole.security.keystore.certificate.alias=brooklyn -{% endhighlight %} - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/cli/cli-ref-guide.md ---------------------------------------------------------------------- diff --git a/guide/ops/cli/cli-ref-guide.md b/guide/ops/cli/cli-ref-guide.md index e3b8c97..09ea9b3 100644 --- a/guide/ops/cli/cli-ref-guide.md +++ b/guide/ops/cli/cli-ref-guide.md @@ -316,7 +316,7 @@ policy pol Add catalog entries from a local YAML file or a URL. The id and version of added entries are displayed. - `br locations` - List the location catalog. (Includes all locations including those defined in `brooklyn.properties`) + List the location catalog. (Includes all locations including those defined in `brooklyn.cfg`) - `br access` Show if you have access to provision locations. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/configuration/brooklyn_cfg.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/brooklyn_cfg.md b/guide/ops/configuration/brooklyn_cfg.md new file mode 100644 index 0000000..bd70ea6 --- /dev/null +++ b/guide/ops/configuration/brooklyn_cfg.md @@ -0,0 +1,215 @@ +--- +title: brooklyn.cfg +layout: website-normal +children: +- { section: Quick Setup } +- { section: Locations } +- { section: Java } +- { section: Authentication } +- { section: Entitlements } +- { section: HTTPS Configuration } +--- + +{% include fields.md %} + +The file brooklyn.cfg is read when Apache Brooklyn starts in order to load any server configuration values. It can be found in the Brooklyn configuration folder. You can check [here](../paths.html) for the location of your Brooklyn configuration folder + +## Quick Setup + +The most common properties set in this file are for access control. Without this, Brooklyn's +web-console and REST api will require no authentication. + +The simplest way to specify users and passwords is shown below (but see the +[Authentication](#authentication) section for how to avoid storing passwords in plain text): + +{% highlight properties %} +brooklyn.webconsole.security.users=admin,bob +brooklyn.webconsole.security.user.admin.password=AdminPassw0rd +brooklyn.webconsole.security.user.bob.password=BobPassw0rd +{% endhighlight %} + +The config file *must* have permissions 600 +(i.e. readable and writable only by the file's owner), +for some security. + +In many cases, it is preferable instead to use an external credentials store such as LDAP. +Information on configuring these is [below](#authentication). + +If coming over a network it is highly recommended additionally to use `https`. +This can be configured with: + +{% highlight properties %} +brooklyn.webconsole.security.https.required=true +{% endhighlight %} + +More information, including setting up a certificate, is described [further below](#https-configuration). + + +## Camp YAML Expressions + +Values in `brooklyn.cfg` can use the Camp YAML syntax. Any value starting `$brooklyn:` is +parsed as a Camp YAML expression. + +This allows [externalized configuration]({{ site.path.guide}}/ops/externalized-configuration.html) to be used from +brooklyn.cfg. For example: + +{% highlight properties %} +brooklyn.location.jclouds.aws-ec2.identity=$brooklyn:external("vault", "aws-identity") +brooklyn.location.jclouds.aws-ec2.credential=$brooklyn:external("vault", "aws-credential") +{% endhighlight %} + +If for some reason one requires a literal value that really does start with `$brooklyn:` (i.e. +for the value to not be parsed), then this can be achieved by using the syntax below. This +example returns the property value `$brooklyn:myexample`: + +{% highlight properties %} +example.property=$brooklyn:literal("$brooklyn:myexample") +{% endhighlight %} + + +## Java + +Arbitrary data can be set in the `brooklyn.cfg`. +This can be accessed in java using `ManagementContext.getConfig(KEY)`. + + +## Authentication + +**Security Providers** are the mechanism by which different authentication authorities are plugged in to Brooklyn. +These can be configured by specifying `brooklyn.webconsole.security.provider` equal +to the name of a class implementing `SecurityProvider`. +An implementation of this could point to Spring, LDAP, OpenID or another identity management system. + +The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords +which should be specified as configuration parameters e.g. in `brooklyn.cfg`. +This configuration could look like: + +{% highlight properties %} +brooklyn.webconsole.security.users=admin +brooklyn.webconsole.security.user.admin.salt=OHDf +brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 +{% endhighlight %} + +The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users. + +To generate this, the brooklyn CLI can be used: + +{% highlight bash %} +brooklyn generate-password --user admin + +Enter password: +Re-enter password: + +Please add the following to your brooklyn.properies: + +brooklyn.webconsole.security.users=admin +brooklyn.webconsole.security.user.admin.salt=OHDf +brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9 +{% endhighlight %} + +Alternatively, in dev/test environments where a lower level of security is required, +the syntax `brooklyn.webconsole.security.user.<username>=<password>` can be used for +each `<username>` specified in the `brooklyn.webconsole.security.users` list. + +Other security providers available include: + +### No one + +`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.BlackholeSecurityProvider` +will block all logins (e.g. if not using the web console) + +### No security + +`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.AnyoneSecurityProvider` +will allow logins with no credentials (e.g. in secure dev/test environments) + +### LDAP + +`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.LdapSecurityProvider` +will cause Brooklyn to call to an LDAP server to authenticate users; +The other things you need to set in `brooklyn.cfg` are: + +* `brooklyn.webconsole.security.ldap.url` - ldap connection url +* `brooklyn.webconsole.security.ldap.realm` - ldap dc parameter (domain) +* `brooklyn.webconsole.security.ldap.ou` *optional, by default it set to Users* - ldap ou parameter + +**brooklyn.cfg example configuration:** + +~~~ +brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.LdapSecurityProvider +brooklyn.webconsole.security.ldap.url=ldap://localhost:10389/????X-BIND-USER=uid=admin%2cou=system,X-BIND-PASSWORD=secret,X-COUNT-LIMIT=1000 +brooklyn.webconsole.security.ldap.realm=example.com +~~~ + +After you setup the brooklyn connection to your LDAP server, you can authenticate in brooklyn using your cn (e.g. John Smith) and your password. +`org.apache.brooklyn.rest.security.provider.LdapSecurityProvider` searches in the LDAP tree in LDAP://cn=John Smith,ou=Users,dc=example,dc=com + +If you want to customize the ldap path or something else which is particular to your LDAP setup you +can extend `LdapSecurityProvider` class or implement from scratch the `SecurityProvider` interface. + + +## Entitlements + +In addition to login access, fine-grained permissions -- including +seeing entities, creating applications, seeing sensors, and invoking effectors -- +can be defined on a per-user *and* per-target (e.g. which entity/effector) basis +using a plug-in **Entitlement Manager**. + +This can be set globally with the property: + +{% highlight properties %} +brooklyn.entitlements.global=<class> +{% endhighlight %} + +The default entitlement manager is one which responds to per-user entitlement rules, +and understands: + +* `root`: full access, including to the Groovy console +* `user`: access to everything but actions that affect the server itself. Such actions include the + Groovy console, stopping the server and retrieving management context configuration. +* `readonly`: read-only access to almost all information +* `minimal`: access only to server stats, for use by monitoring systems + +These keywords are also understood at the `global` level, so to grant full access to `admin`, +read-only access to `support`, limited access to `metrics` and regular access to `user` +you can write: + +{% highlight properties %} +brooklyn.entitlements.global=user +brooklyn.entitlements.perUser.admin=root +brooklyn.entitlements.perUser.support=readonly +brooklyn.entitlements.perUser.metrics=minimal +{% endhighlight %} + +Under the covers this invokes the `PerUserEntitlementManager`, +with a `default` set (and if not specified `default` defaults to `minimal`); +so the above can equivalently be written: + +{% highlight properties %} +brooklyn.entitlements.global=org.apache.brooklyn.core.mgmt.entitlement.PerUserEntitlementManager +brooklyn.entitlements.perUser.default=user +brooklyn.entitlements.perUser.admin=root +brooklyn.entitlements.perUser.support=readonly +brooklyn.entitlements.perUser.metrics=minimal +{% endhighlight %} + +For more information, see +[Java: Entitlements]({{ site.path.guide }}/blueprints/java/entitlements.html). +or +{% include java_link.html class_name="EntitlementManager" package_path="org/apache/brooklyn/api/mgmt/entitlement" project_subpath="api" %}. + + + +## HTTPS Configuration + +See [HTTPS Configuration](https.html) for general information on configuring HTTPS. + +To enable HTTPS in Brooklyn, add the following to your brooklyn.cfg: + +{% highlight properties %} +brooklyn.webconsole.security.https.required=true +brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key +brooklyn.webconsole.security.keystore.password=mypassword +brooklyn.webconsole.security.keystore.certificate.alias=brooklyn +{% endhighlight %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/configuration/cors.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/cors.md b/guide/ops/configuration/cors.md new file mode 100644 index 0000000..03fefd6 --- /dev/null +++ b/guide/ops/configuration/cors.md @@ -0,0 +1,45 @@ +--- +title: CORS Configuration +layout: website-normal +--- + +To enable / configure [cross-origin resource sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing). +The following file must be added to [`<brooklyn-config-directory>/org.apache.brooklyn.rest.filter.cors.cfg`](../paths.html) + +{% highlight properties %} +# Enables experimental support for Cross Origin Resource Sharing (CORS) filtering in Apache Brooklyn REST API. +cors.enabled=true + +# @see CrossOriginResourceSharingFilter#setAllowOrigins(List<String>) +# Coma separated values list of allowed origins. Access-Control-Allow-Origin header will be returned to client if Origin header in request is matching exactly a value among the list allowed origins. +# If empty or not specified then all origins are allowed. No wildcard allowed origins are supported. +cors.allow.origins=http://host-one.example.com:8080, http://host-two.example.com, https://host-three.example.com + +# @see CrossOriginResourceSharingFilter#setAllowHeaders(List<String>) +# Coma separated values list of allowed headers for preflight checks. +#cors.allow.headers= + +# @see CrossOriginResourceSharingFilter#setAllowCredentials(boolean) +# The value for the Access-Control-Allow-Credentials header. If false, no header is added. +# If true, the header is added with the value 'true'. False by default. +#cors.allow.credentials=false + +# @see CrossOriginResourceSharingFilter#setExposeHeaders(List<String>) +# CSV list of non-simple headers to be exposed via Access-Control-Expose-Headers. +#cors.expose.headers= + +# @see CrossOriginResourceSharingFilter#setMaxAge(Integer) +# The value for Access-Control-Max-Age. If -1 then No Access-Control-Max-Age header will be send. +#cors.max.age=-1 + +# @see CrossOriginResourceSharingFilter#setPreflightErrorStatus(Integer) +# Preflight error response status, default is 200. +cors.preflight.error.status=200 + +# Do not apply CORS if response is going to be with UNAUTHORIZED status. +#cors.block.if.unauthorized=false +{% endhighlight %} + +*NOTE*: You must [restart Brooklyn](../starting-stopping-monitoring.html) for these changes to be applied + +Further information on client side [usage](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/configuration/https.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/https.md b/guide/ops/configuration/https.md new file mode 100644 index 0000000..debb4f0 --- /dev/null +++ b/guide/ops/configuration/https.md @@ -0,0 +1,52 @@ +--- +title: HTTPS Configuration +layout: website-normal +--- + +## Getting the Certificate +To enable HTTPS web access, you will need a server certificate in a java keystore. To create a self-signed certificate, +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 \ + -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword" \ + -validity 365 -keysize 2048 -keypass "password" +{% endhighlight %} + +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 +used in your brooklyn.cfg (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`. + +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_cfg.html#https-configuration) +* [Karaf Distribution](osgi-configuration.html#https-configuration) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/configuration/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/index.md b/guide/ops/configuration/index.md new file mode 100644 index 0000000..327d55c --- /dev/null +++ b/guide/ops/configuration/index.md @@ -0,0 +1,50 @@ +--- +title_in_menu: Configuring Brooklyn +title: Brooklyn Configuration and Options +layout: website-normal +children: +- { section: Memory Usage } +- { section: Authentication } +- brooklyn_cfg.md +- https.md +- osgi-configuration.md +- cors.md +--- + +Apache Brooklyn contains a number of configuration options managed across several files. +Historically Brooklyn has been configured through a brooklyn.properties file, this changed +to a [brooklyn.cfg](brooklyn_cfg.html) file when the Karaf release became the default in Brooklyn 0.12.0. + +The configurations for [persistence](../persistence/index.html) and [high availability](../high-availability/index.html) are described +elsewhere in this manual. + +### Memory Usage + +The amount of memory required by Apache Brooklyn process depends on the usage - for example the number of entities/VMs under management. + +For a standard Brooklyn deployment, the defaults are to start with 256m, and to grow to 2g of memory. These numbers can be overridden +by setting the `JAVA_MAX_MEM` and `JAVA_MAX_PERM_MEM` in the `bin/setenv` script: + + export JAVA_MAX_MEM="2G" + +Apache Brooklyn stores a task history in-memory using [soft references](http://docs.oracle.com/javase/7/docs/api/java/lang/ref/SoftReference.html). +This means that, once the task history is large, Brooklyn will continually use the maximum allocated memory. It will +only expunge tasks from memory when this space is required for other objects within the Brooklyn process. + +### Authentication and Security + +There are two areas of authentication used in Apache Brooklyn, these are as follows: + +* Karaf authentication + +Apache Brooklyn uses [Apache Karaf](https://karaf.apache.org) as a core platform, this has user level security and +groups which can be configured as detailed [here](https://karaf.apache.org/manual/latest/security#_users_groups_roles_and_passwords). + +* Apache Brooklyn authentication + +Users and passwords for Brooklyn can be configured in the brooklyn.cfg as detailed [here](brooklyn_cfg.html#authentication). + +### HTTPS Configuration + +For information on securing your Apache Brooklyn installation with HTTPS, please refer to the pages on [setting up a certificate and keystore](https.html) and +[configuring this in Brooklyn](osgi-configuration.html#https-configuration). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/configuration/osgi-configuration.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/osgi-configuration.md b/guide/ops/configuration/osgi-configuration.md new file mode 100644 index 0000000..2dfa681 --- /dev/null +++ b/guide/ops/configuration/osgi-configuration.md @@ -0,0 +1,119 @@ +--- +title: OSGi Configuration +layout: website-normal +--- + +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](https://karaf.apache.org/manual/latest/) 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/e73b66e0/guide/ops/externalized-configuration.md ---------------------------------------------------------------------- diff --git a/guide/ops/externalized-configuration.md b/guide/ops/externalized-configuration.md index 941e277..802fa75 100644 --- a/guide/ops/externalized-configuration.md +++ b/guide/ops/externalized-configuration.md @@ -9,15 +9,15 @@ plain-text password for a production system, especially if (as we often recommen developer's source code control system. To handle this problem, Apache Brooklyn supports externalized configuration. This allows a blueprint to refer to -a piece of information that is stored elsewhere. `brooklyn.properties` defines the external suppliers of configuration +a piece of information that is stored elsewhere. `brooklyn.cfg` defines the external suppliers of configuration information. At runtime, when Brooklyn finds a reference to externalized configuration in a blueprint, it consults -`brooklyn.properties` for information about the supplier, and then requests that the supplier return the information +`brooklyn.cfg` for information about the supplier, and then requests that the supplier return the information required by the blueprint. Take, as a simple example, a web app which connects to a database. In development, the developer is running a local instance of PostgreSQL with a simple username and password. But in production, an enterprise-grade cluster of PostgreSQL is used, and a dedicated service is used to provide passwords. The same blueprint can be used to service both groups -of users, with `brooklyn.properties` changing the behaviour depending on the deployment environment. +of users, with `brooklyn.cfg` changing the behaviour depending on the deployment environment. Here is the blueprint: @@ -43,7 +43,7 @@ the first is the name of the configuration supplier, the second is the name of a supplier. In this case we are using two different suppliers: `servers` to store the location of the server, and `credentials` which is a security-optimized supplier of secrets. -Developers would add lines like this to the `brooklyn.properties` file on their workstation: +Developers would add lines like this to the `brooklyn.cfg` file on their workstation: {% highlight properties %} brooklyn.external.servers=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier @@ -53,9 +53,9 @@ brooklyn.external.credentials.postgresql-user=admin brooklyn.external.credentials.postgresql-password=admin {% endhighlight %} -In this case, all of the required information is included in-line in the local `brooklyn.properties`. +In this case, all of the required information is included in-line in the local `brooklyn.cfg`. -Whereas in production, `brooklyn.properties` might look like this: +Whereas in production, `brooklyn.cfg` might look like this: {% highlight properties %} brooklyn.external.servers=org.apache.brooklyn.core.config.external.PropertiesFileExternalConfigSupplier @@ -83,7 +83,7 @@ brooklyn.external.brooklyn-demo-sample.hidden-brooklyn-password=new_password ## Defining Suppliers -External configuration suppliers are defined in `brooklyn.properties`. The minimal definition is of the form: +External configuration suppliers are defined in `brooklyn.cfg`. The minimal definition is of the form: brooklyn.external.*supplierName* = *className* @@ -92,7 +92,7 @@ will provide the behaviour of how to retrieve data from the supplier. Brooklyn i implementations; see below for more details. Suppliers may require additional configuration options. These are given as additional properties in -`brooklyn.properties`: +`brooklyn.cfg`: {% highlight properties %} brooklyn.external.supplierName = className @@ -128,9 +128,9 @@ brooklyn.config: {% endhighlight %} -## Referring to External Configuration in brooklyn.properties +## Referring to External Configuration in brooklyn.cfg -The same blueprint language DSL can be used from `brooklyn.properties`. For example: +The same blueprint language DSL can be used from `brooklyn.cfg`. For example: {% highlight properties %} brooklyn.location.jclouds.aws-ec2.identity=$brooklyn:external("mysupplier", "aws-identity") @@ -162,7 +162,7 @@ Brooklyn ships with a number of external configuration suppliers ready to use. ### In-place -**InPlaceExternalConfigSupplier** embeds the configuration keys and values as properties inside `brooklyn.properties`. +**InPlaceExternalConfigSupplier** embeds the configuration keys and values as properties inside `brooklyn.cfg`. For example: {% highlight properties %} @@ -198,7 +198,7 @@ Then, a blueprint which referred to `$brooklyn:external("servers", "postgresql") able to query the Vault REST API for configuration values. The different suppliers implement alternative authentication options that Vault provides. -For *all* of the authentication methods, you must always set these properties in `brooklyn.properties`: +For *all* of the authentication methods, you must always set these properties in `brooklyn.cfg`: {% highlight properties %} brooklyn.external.supplierName.endpoint=<Vault HTTP/HTTPs endpoint> @@ -244,7 +244,7 @@ brooklyn.external.supplierName.userId=server3.cluster2.europe #### Authentication by fixed token If you have a fixed token string, then you can use the *VaultTokenExternalConfigSupplier* class and provide the token -in `brooklyn.properties`: +in `brooklyn.cfg`: {% highlight properties %} brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultTokenExternalConfigSupplier @@ -267,4 +267,4 @@ String get(String key); {% endhighlight %} Classes implementing this interface can be placed in the `lib/dropins` folder of Brooklyn, and then the supplier -defined in `brooklyn.properties` as normal. \ No newline at end of file +defined in `brooklyn.cfg` as normal. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/gui/running.md ---------------------------------------------------------------------- diff --git a/guide/ops/gui/running.md b/guide/ops/gui/running.md index 05ed0fa..b94f152 100644 --- a/guide/ops/gui/running.md +++ b/guide/ops/gui/running.md @@ -17,8 +17,8 @@ If you haven't already done so, you will need to start Brooklyn Server using the It is not necessary at this time, but depending on what you are going to do, you may wish to set up some other configuration options first, -* [Security](../brooklyn_properties.html) -* [Persistence](../persistence/) +* [Security]({{ site.path.guide }}/ops/configuration/brooklyn_cfg.html) +* [Persistence]({{ site.path.guide }}/ops/persistence/) Now start Brooklyn with the following command: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/high-availability/high-availability-supplemental.md ---------------------------------------------------------------------- diff --git a/guide/ops/high-availability/high-availability-supplemental.md b/guide/ops/high-availability/high-availability-supplemental.md index 7b663fb..33f597f 100644 --- a/guide/ops/high-availability/high-availability-supplemental.md +++ b/guide/ops/high-availability/high-availability-supplemental.md @@ -1,9 +1,9 @@ --- -title: High Availability (Supplemental) +title: Configuring HA - an example layout: website-normal --- -This document supplements the [High Availability]({{ site.path.guide }}/ops/high-availability/) documentation +This supplements the [High Availability](../) documentation and provides an example of how to configure a pair of Apache Brooklyn servers to run in master-standby mode with a shared NFS datastore ### Prerequisites @@ -12,26 +12,38 @@ and provides an example of how to configure a pair of Apache Brooklyn servers to - An NFS folder has been mounted on both VMs at `/mnt/brooklyn-persistence` and both machines can write to the folder \* Brooklyn can be configured to use either an object store such as S3, or a shared NFS mount. The recommended option is to use an object -store as described in the [Object Store Persistence]({{ site.path.guide }}/ops/persistence/#object-store-persistence) documentation. For simplicity, a shared NFS folder +store as described in the [Object Store Persistence]({{ site.path.operations }}/ops/persistence/#object-store-persistence) documentation. For simplicity, a shared NFS folder is assumed in this example ### Launching To start, download and install the latest Apache Brooklyn release on both VMs following the instructions in -[Running Apache Brooklyn]({{ site.path.guide }}/start/running.html#install-apache-brooklyn) +[Running Apache Brooklyn]({{ site.path.tutorials }}/start/running.html) -On the first VM, which will be the master node, run the following to start Brooklyn in high availability mode: +On the first VM, which will be the master node, set the following configuration options: + +- highAvailabilityMode: MASTER +- persistMode: AUTO +- persistenceDir: /mnt/brooklyn-persistence + +Then launch Brooklyn with: {% highlight bash %} -$ bin/brooklyn launch --highAvailability master --https --persist auto --persistenceDir /mnt/brooklyn-persistence +$ bin/start {% endhighlight %} -If you are using RPMs/deb to install, please see the [Running Apache Brooklyn]({{ site.path.guide }}/start/running.html#install-apache-brooklyn) +If you are using RPMs/deb to install, please see the [Running Apache Brooklyn]({{ site.path.tutorials }}/start/running.html) documentation for the appropriate launch commands -Once Brooklyn has launched, on the second VM, run the following command to launch Brooklyn in standby mode: +Once Brooklyn has launched, on the second VM, set the following configuration options ([`org.apache.brooklyn.osgilauncher.cfg`](../paths.html)): + +- highAvailabilityMode: AUTO +- persistMode: AUTO +- persistenceDir: /mnt/brooklyn-persistence + +Then launch the standby Brooklyn with: {% highlight bash %} -$ bin/brooklyn launch --highAvailability auto --https --persist auto --persistenceDir /mnt/brooklyn-persistence +$ bin/start {% endhighlight %} ### Failover @@ -39,7 +51,7 @@ When running as a HA standby node, each standby Brooklyn server (in this case th every one second to determine the state of the HA master. If no heartbeat has been recorded for 30 seconds, then an election will be performed and one of the standby nodes will be promoted to master. At this point all requests should be directed to the new master node. If the master is terminated gracefully, the secondary will be immediately promoted to mater. Otherwise, the secondary will be promoted after -heartbeats are missed for a given length of time. This defaults to 30 seconds, and is configured in brooklyn.properties using +heartbeats are missed for a given length of time. This defaults to 30 seconds, and is configured in brooklyn.cfg using `brooklyn.ha.heartbeatTimeout` In the event that tasks - such as the provisioning of a new entity - are running when a failover occurs, the new master will display the current @@ -153,3 +165,4 @@ added for clarity): The examples above show how to use `curl` to manually check the status of Brooklyn via its REST API. The same REST API calls can also be used by automated third party monitoring tools such as Nagios + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/high-availability/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/high-availability/index.md b/guide/ops/high-availability/index.md index 5fc244e..368ad22 100644 --- a/guide/ops/high-availability/index.md +++ b/guide/ops/high-availability/index.md @@ -27,15 +27,15 @@ Once one node is running as `MASTER`, other nodes start in either `STANDBY` or ` entities, as a read-only copy. However this node is not able to become master, so it can safely be used to test compatibility across different versions. -To explicitly specify what HA mode a node should be in, the following CLI options are available -for the parameter `--highAvailability`: - -* `disabled`: management node works in isolation; it will not cooperate with any other standby/master nodes in management plane -* `auto`: will look for other management nodes, and will allocate itself as standby or master based on other nodes' states -* `master`: will startup as master; if there is already a master then fails immediately -* `standby`: will start up as lukewarm standby; if there is not already a master then fails immediately -* `hot_standby`: will start up as hot standby; if there is not already a master then fails immediately -* `hot_backup`: will start up as hot backup; this can be done even if there is not already a master; this node will not be a master +To explicitly specify what HA mode a node should be in, the following options are available +for the config option `highAvailabilityMode` in [`org.apache.brooklyn.osgilauncher.cfg`](../paths.html): + +* `DISABLED`: management node works in isolation; it will not cooperate with any other standby/master nodes in management plane +* `AUTO`: will look for other management nodes, and will allocate itself as standby or master based on other nodes' states +* `MASTER`: will startup as master; if there is already a master then fails immediately +* `STANDBY`: will start up as lukewarm standby; if there is not already a master then fails immediately +* `HOT_STANDBY`: will start up as hot standby; if there is not already a master then fails immediately +* `HOT_BACKUP`: will start up as hot backup; this can be done even if there is not already a master; this node will not be a master The REST API offers live detection and control of the HA mode, including setting priority to control which nodes will be promoted on master failure: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/https.md ---------------------------------------------------------------------- diff --git a/guide/ops/https.md b/guide/ops/https.md deleted file mode 100644 index 7ed910c..0000000 --- a/guide/ops/https.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: HTTPS Configuration -layout: website-normal ---- - -## Getting the Certificate -To enable HTTPS web access, you will need a server certificate in a java keystore. To create a self-signed certificate, -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 \ - -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword" \ - -validity 365 -keysize 2048 -keypass "password" -{% endhighlight %} - -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 -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`. - -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/e73b66e0/guide/ops/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/index.md b/guide/ops/index.md index 110c0b9..29b5061 100644 --- a/guide/ops/index.md +++ b/guide/ops/index.md @@ -9,12 +9,10 @@ children: - cli/ - gui/ - rest.md -- brooklyn_properties.md +- configuration/ - persistence/ - high-availability/ -- osgi.md - logging.md -- https.md - externalized-configuration.md - requirements.md - upgrade.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/osgi-configuration.md ---------------------------------------------------------------------- diff --git a/guide/ops/osgi-configuration.md b/guide/ops/osgi-configuration.md deleted file mode 100644 index 2dfa681..0000000 --- a/guide/ops/osgi-configuration.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: OSGi Configuration -layout: website-normal ---- - -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](https://karaf.apache.org/manual/latest/) 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/e73b66e0/guide/ops/osgi.md ---------------------------------------------------------------------- diff --git a/guide/ops/osgi.md b/guide/ops/osgi.md deleted file mode 100644 index 8c26849..0000000 --- a/guide/ops/osgi.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: OSGi Distribution -layout: website-normal -children: -- osgi-configuration.md ---- - -The Apache Brooklyn Karaf based distribution lives in brooklyn-dist/karaf/apache-brooklyn folder. -Please contact us on the -[mailing list](mailto:[email protected]) if you find any problems. - -## Building - -{% highlight bash %} -cd brooklyn-dist -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 with a console in the foreground using the following command - -{% highlight bash %} -bin/karaf -{% endhighlight %} - -This will launch the [Karaf console](https://karaf.apache.org/manual/latest/#_using_the_console) -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. - -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. - -## Debugging - -To start in debug mode use - -{% highlight bash %} -bin/karaf debug -{% endhighlight %} - -and connect to port 5005 using your normal Java debugger. - -If you want to change dt_socket port you can pass `JAVA_DEBUG_PORT` environment variable - -{%highlight bash %} -JAVA_DEBUG_PORT=5006 bin/karaf debug -{% endhighlight %} - -To pause startup until the debugger is connected you can use - -{% highlight bash %} -JAVA_DEBUG_OPTS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005' bin/karaf debug -{% endhighlight %} - -For other options please check your JVM JPDA documentation. -Hotspot JPDA: https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/ - -## 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. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/paths.md ---------------------------------------------------------------------- diff --git a/guide/ops/paths.md b/guide/ops/paths.md new file mode 100644 index 0000000..cb6d554 --- /dev/null +++ b/guide/ops/paths.md @@ -0,0 +1,49 @@ +--- +layout: website-normal +title: Paths breakdown +--- + +Based on the installation method you choose, the paths to the installed components of Apache Brooklyn will be different. The +following table will help you to easily locate these: + +<table class="table"> + <thead> + <tr> + <th>Installation method</th> + <th>Brooklyn Home</td> + <th>Brooklyn Logs</th> + <th>Brooklyn Configuration</th> + <th>Brooklyn Persisted state</th> + </tr> + </thead> + <tbody> + <tr> + <td>RPM Package</td> + <td><code>/opt/booklyn</code> (symlink to <code>/opt/booklyn-<version></code>)</td> + <td><code>/var/log/booklyn</code> (symlink to <code>/opt/booklyn-<version>/data/log</code>)</td> + <td><code>/etc/booklyn</code></td> + <td><code>/var/lib/booklyn</code></td> + </tr> + <tr> + <td>DEB Package</td> + <td><code>/opt/booklyn</code> (symlink to <code>/opt/booklyn-<version></code>)</td> + <td><code>/var/log/booklyn</code> (symlink to <code>/opt/booklyn-<version>/data/log</code>)</td> + <td><code>/etc/booklyn</code></td> + <td><code>/var/lib/booklyn</code></td> + </tr> + <tr> + <td>Vagrant</td> + <td><code>/opt/booklyn</code> (symlink to <code>/opt/booklyn-<version></code>)</td> + <td><code>/var/log/booklyn</code> (symlink to <code>/opt/booklyn-<version>/data/log</code>)</td> + <td><code>/etc/booklyn</code></td> + <td><code>/var/lib/booklyn</code></td> + </tr> + <tr> + <td>Tarball Zip Package</td> + <td><code>/path/of/untar/archive</code></td> + <td><code>/path/of/untar/archive/data/log</code></td> + <td><code>/path/of/untar/archive/etc</code></td> + <td><code>~/.brooklyn/brooklyn-persisted-state</code></td> + </tr> + </tbody> +</table> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/persistence/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/persistence/index.md b/guide/ops/persistence/index.md index 4d19062..52d47da 100644 --- a/guide/ops/persistence/index.md +++ b/guide/ops/persistence/index.md @@ -2,7 +2,7 @@ title: Persistence layout: website-normal children: -- { section: Command Line Options } +- { section: Configuration } - { section: File-based Persistence } - { section: Object Store Persistence } - { section: Rebinding to State } @@ -10,98 +10,70 @@ children: - { section: Persisted State Backup } --- -Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted, -or so that a high availability standby server can take over. +By default Brooklyn persists its state to storage so that a server can be restarted +without loss or so a high availability standby server can take over. -Brooklyn can persist its state to one of two places: the file system, or to an Object Store +Brooklyn can persist its state to one of two places: the file system, or to an [object store](https://en.wikipedia.org/wiki/Object_storage) of your choice. -Command Line Options --------------------- -To configure brooklyn, the relevant command line options for the `launch` commands are: +# Configuration -* `--persist` <persistence mode> - The persistence mode. -* `--persistenceDir` <persistence dir> - The directory to read/write persisted state (or container name if using an object store). -* `--persistenceLocation` <persistence location> - The location spec for an object store to read/write persisted state. +To configure persistence, edit the file `org.apache.brooklyn.osgilauncher.cfg` in the `etc` +directory of your Brooklyn instance. The following options are available: -For the persistence mode, the possible values are: +`persistMode` - This is the mode in which persistence is running, in and is set to `AUTO` by default. The possible values are: -* `disabled` means that no state will be persisted or read; when Brooklyn stops all state is lost. -* `rebind` means that it will read existing state, and recreate entities, locations and policies - from that. If there is no existing state, startup will fail. -* `clean` means that any existing state will be deleted, and Brooklyn will be started afresh. -* `auto` means Brooklyn will rebind if there is any existing state, or will start afresh if - there is no state. +* `AUTO` - will rebind to any existing state, or start up fresh if no state; +* `DISABLED` - will not read or persist any state; +* `REBIND` - will rebind to the existing state, or fail if no state available; +* `CLEAN` - will start up fresh (removing any existing state) -The persistence directory and location can instead be specified from `brooklyn.properties` using -the following config keys: +`persistenceDir` - This is the directory to which Apache Brooklyn reads and writes its persistence data. The default location depends +on your installation method. Checkout [this page](../paths.html) for more information. -* `brooklyn.persistence.dir` -* `brooklyn.persistence.location.spec` +`persistenceLocation` - This is the location for an object store to read and write persisted state. +`persistPeriod` - This is an interval period which can be set to reduce the frequency with which persistence +is carried out, for example `1s`. -File-based Persistence ----------------------- -To persist to the file system, start brooklyn with: +# File-based Persistence -{% highlight bash %} -brooklyn launch --persist auto --persistenceDir /path/to/myPersistenceDir -{% endhighlight %} +Apache Brooklyn starts with file-based persistence by default, saving data in the [persisted state folder](../paths.html). +For the rest of this document we will refer to this location as `%persistence-home%`. -If there is already data at `/path/to/myPersistenceDir`, then a backup of the directory will -be made. This will have a name like `/path/to/myPersistenceDir.20140701-142101345.bak`. +If there is already data at `%persistence-home%/data`, then a backup of the directory will +be made. This will have a name like `%persistence-home%/backups/%date%-%time%-jvyX7Wis-promotion-igFH`. +This means backups of the data directory will be automatically created each time Brooklyn +is restarted (or if a standby Brooklyn instances takes over as master). The state is written to the given path. The file structure under that path is: +* `./catalog/` +* `./enrichers/` * `./entities/` +* `./feeds/` * `./locations/` +* `./nodes/` +* `./plane/` * `./policies/` -* `./enrichers/` In each of those directories, an XML file will be created per item - for example a file per entity in `./entities/`. This file will capture all of the state - for example, an entity's: id; display name; type; config; attributes; tags; relationships to locations, child entities, group membership, policies and enrichers; and dynamically added effectors and sensors. -If using the default persistence dir (i.e. no `--persistenceDir` was specified), then Brooklyn will -write its state to `~/.brooklyn/brooklyn-persisted-state/data`. Copies of this directory -will be automatically created in `~/.brooklyn/brooklyn-persisted-state/backups/` each time Brooklyn -is restarted (or if a standby Brooklyn instances takes over as master). - -A custom directory for Brooklyn state can also be configured in `brooklyn.properties` using: - - # For all Brooklyn files - brooklyn.base.dir=/path/to/base/dir - - # Sub-directory of base.dir for writing persisted state (if relative). If directory - # starts with "/" (or "~/", or something like "c:\") then assumed to be absolute. - brooklyn.persistence.dir=data - - # Sub-directory of base.dir for creating backup directories (if relative). If directory - # starts with "/" (or "~/", or something like "c:\") then assumed to be absolute. - brooklyn.persistence.backups.dir=backups - -This `base.dir` will also include temporary files such as the OSGi cache. - -If `persistence.dir` is not specified then it will use the sub-directory -`brooklyn-persisted-state/data` of the `base.dir`. If the `backups.dir` is not specified -the backup directories will be created in the sub-directory `backups` of the persistence dir. +# Object Store Persistence -Object Store Persistence ------------------------- - -Brooklyn can persist its state to any Object Store API that jclouds supports including -S3, Swift and Azure. This gives access to any compatible Object Store product or cloud provider -including AWS-S3, SoftLayer, Rackspace and Microsoft Azure. For a complete list of supported +Apache Brooklyn can persist its state to any Object Store API supported by [Apache jclouds](https://jclouds.apache.org/) including +[S3](https://aws.amazon.com/s3), [Swift](http://docs.openstack.org/developer/swift) and [Azure](https://azure.microsoft.com/services/storage/). +This gives access to any compatible Object Store product or cloud provider including AWS-S3, +SoftLayer, Rackspace, HP and Microsoft Azure. For a complete list of supported providers, see [jclouds](http://jclouds.apache.org/reference/providers/#blobstore). -To configure the Object Store, add the credentials to `~/.brooklyn/brooklyn.properties` such as: +To configure the Object Store, add the credentials to `brooklyn.cfg` such as: {% highlight properties %} brooklyn.location.named.aws-s3-eu-west-1=aws-s3:eu-west-1 @@ -118,33 +90,9 @@ brooklyn.location.named.softlayer-swift-ams01.credential=abcdefghijklmnopqrstuvw brooklyn.location.named.softlayer-swift-ams01.jclouds.keystone.credential-type=tempAuthCredentials {% endhighlight %} -Start Brooklyn pointing at this target object store, e.g.: - -{% highlight bash %} -nohup brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLocation named:softlayer-swift-ams01 & -{% endhighlight %} - - -The following `brooklyn.properties` options can also be used: - - # Location spec string for an object store (e.g. jclouds:openstack-swift:URL) where persisted state - # should be kept; if blank or not supplied, the file system is used. - brooklyn.persistence.location.spec=<location> +Then edit the `persistenceLocation` to point at this object store: `softlayer-swift-ams01`. - # Container name for writing persisted state - brooklyn.persistence.dir=/path/to/dataContainer - - # Location spec string for an object store (e.g. jclouds:openstack-swift:URL) where backups of - # persisted state should be kept; defaults to the local file system. - brooklyn.persistence.backups.location.spec=<location> - - # Container name for writing backups of persisted state; - # defaults to 'backups' inside the default persistence container. - brooklyn.persistence.backups.dir=/path/to/backupContainer - - -Rebinding to State ------------------- +# Rebinding to State When Brooklyn starts up pointing at existing state, it will recreate the entities, locations and policies based on that persisted state. @@ -155,93 +103,21 @@ HTTP or JMX). This new state will be reported in the web-console and can also tr any registered policies. -## CLI Commands for Copying State - -Brooklyn includes a command to copy persistence state easily between two locations. -The `copy-state` CLI command takes the following arguments: - -* `--persistenceDir` <source persistence dir> - The directory to read persisted state (or container name if using an object store). -* `--persistenceLocation` <source persistence location> - The location spec for an object store to read persisted state. -* `--destinationDir` <target persistence dir> - The directory to copy persistence data to (or container name if using an object store). -* `--destinationLocation` <target persistence location> - The location spec for an object store to copy data to. -* `--transformations` <transformations> - The local transformations file to be applied to the copy of the data before uploading it. - -## CLI Commands for Cleaning Orphaned State - -Brooklyn includes a command to clean orphaned state which uses the copy state command -and removes orphaned locations, enrichers, policies and feeds from the copied state. -The `clean-orphaned-state` CLI command takes the following arguments: - -* `--persistenceDir` <source persistence dir> - The directory to read persisted state (or container name if using an object store). -* `--persistenceLocation` <source persistence location> - The location spec for an object store to read persisted state. -* `--destinationDir` <target persistence dir> - The directory to copy persistence data to, with orphaned state removed. -* `--destinationLocation` <target persistence location> - The location spec for an object store to copy data to. - ## Handling Rebind Failures If rebind fails fail for any reason, details of the underlying failures will be reported -in the `brooklyn.debug.log`. There are several approaches to resolving problems. +in the [`brooklyn.debug.log`](../paths.html). This will include the entities, locations or policies which caused an issue, and in what +way it failed. There are several approaches to resolving problems. +1) Determine Underlying Cause -### Determine Underlying Cause +Go through the log and identify the likely areas in the code from the error message. -The problems reported in brooklyn.debug.log will indicate where the problem lies - which -entities, locations or policies, and in what way it failed. - -### Ignore Errors - -The `~/.brooklyn/brooklyn.properties` has several configuration options: - -{% highlight properties %} -rebind.failureMode.danglingRef=continue -rebind.failureMode.loadPolicy=continue -rebind.failureMode.addPolicy=continue -rebind.failureMode.rebind=fail_at_end -rebind.failureMode.addConfig=fail_at_end -{% endhighlight %} +2) Seek Help -For each of these configuration options, the possible values are: + Help can be found by contacting the Apache Brooklyn mailing list. -* `fail_fast`: stop rebind immediately upon errors; do not try to rebind other entities -* `fail_at_end`: continue rebinding all entities, but then fail so that all errors - encountered are reported -* `continue`: log a warning, but ignore the error to continue rebinding. Depending on the - type of error, this can cause serious problems later (e.g. if the state of an entity - was entirely missing, then all its children would be orphaned). - -The meaning of the configuration options is: - -* `rebind.failureMode.dangingRef`: if there is a reference to an entity, location or policy - that is missing... whether to continue (discarding the reference) or fail. -* `rebind.failureMode.loadPolicy`: if there is an error instantiate or reconstituting the - state of a policy or enricher... whether to continue (discarding the policy or enricher) - or fail. -* `rebind.failureMode.addPolicy`: if there is an error re-adding the policy or enricher to - its associated entity... whether to continue (discarding the policy or enricher) - or fail. -* `rebind.failureMode.addConfig`: if there is invalid config value, or some other error occurs when adding a config. -* `rebind.failureMode.rebind`: any errors on rebind not covered by the more specific error cases described above. - - -### Seek Help - -Help can be found at `[email protected]`, where folk will be able to investigate -issues and suggest work-arounds. - -By sharing the persisted state (with credentials removed), Brooklyn developers will be able to -reproduce and debug the problem. - - -### Fix-up the State +3) Fix-up the State The state of each entity, location, policy and enricher is persisted in XML. It is thus human readable and editable. @@ -251,7 +127,7 @@ an offending entity could be removed, or references to that entity removed, or i could be fixed to remove the problem. -### Fixing with Groovy Scripts +4) Fixing with Groovy Scripts The final (powerful and dangerous!) tool is to execute Groovy code on the running Brooklyn instance. If authorized, the REST api allows arbitrary Groovy scripts to be passed in and @@ -262,8 +138,8 @@ instance. After fixing the entities, locations and/or policies, the Brooklyn ins new persisted state can be copied and used to fix the production instance. -Writing Persistable Code ------------------------- +# Writing Persistable Code + The most common problem on rebind is that custom entity code has not been written in a way that can be persisted and/or rebound. @@ -313,7 +189,7 @@ Behaviour on rebind: * By extending `SoftwareProcess`, entities get a lot of the rebind logic for free. For example, the default `rebind()` method will call `connectSensors()`. - See [`SoftwareProcess` Lifecycle]({{site.path.guide}}/blueprints/java/entities.html#SoftwareProcess-lifecycle) + See [`SoftwareProcess` Lifecycle](/blueprints/java/entities.html) for more details. * If necessary, implement rebind. The `entity.rebind()` is called automatically by the Brooklyn framework on rebind, after configuring the entity's config/attributes but before @@ -339,8 +215,7 @@ Below are tips to make backwards-compatibility easier for persisted state: part of an upgrade process. -Persisted State Backup ----------------------- +# Persisted State Backup ### File system backup http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/e73b66e0/guide/ops/production-installation.md ---------------------------------------------------------------------- diff --git a/guide/ops/production-installation.md b/guide/ops/production-installation.md index 2b870c4..7825bdc 100644 --- a/guide/ops/production-installation.md +++ b/guide/ops/production-installation.md @@ -9,7 +9,7 @@ To install Apache Brooklyn on a production server: 1. [Set up the prerequisites](#prerequisites) 1. [Download Apache Brooklyn](#download) -1. [Configuring brooklyn.properties](#configuring-properties) +1. [Configuring brooklyn.cfg](#configuring-properties) 1. [Configuring Karaf Security](#configuring-karaf-security) 1. [Configuring default.catalog.bom](#configuring-catalog) 1. [Test the installation](#confirm) @@ -69,22 +69,14 @@ Let's setup some paths for easy commands. {% endhighlight %} -### <a id="configuring-properties"></a>Configuring brooklyn.properties +### <a id="configuring-properties"></a>Configuring brooklyn.cfg -Set up `brooklyn.properties` as described [here](brooklyn_properties.html): +Set up `brooklyn.cfg` as described [here](brooklyn_cfg.html): * Configure the users who should have access * Turn on HTTPS * Supply credentials for any pre-defined clouds -It may be useful to use the following script to install an initial `brooklyn.properties`: - -{% highlight bash %} -% mkdir -p ~/.brooklyn -% wget -O ~/.brooklyn/brooklyn.properties {{brooklyn_properties_url_live}} -% chmod 600 ~/.brooklyn/brooklyn.properties -{% endhighlight %} - ### <a id="configuring-karaf-security"></a>Configuring Karaf Security Out of the box, Apache Brooklyn includes the default Karaf security configuration.
