http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/cli/cli-usage-guide.md ---------------------------------------------------------------------- diff --git a/guide/ops/cli/cli-usage-guide.md b/guide/ops/cli/cli-usage-guide.md index 7e335b9..e25f7a3 100644 --- a/guide/ops/cli/cli-usage-guide.md +++ b/guide/ops/cli/cli-usage-guide.md @@ -26,43 +26,43 @@ conjunction with a shell pipeline like `some_command | cut -f 1 -d '|' | xargs - First, login to the running Brooklyn server. This example assumes that the Brooklyn server is running on `localhost`; change the URL and credentials as necessary. -{% highlight text %} +```text $ br login http://localhost:8081 admin Enter Password: * Connected to Brooklyn version 0.9.0-SNAPSHOT at http://localhost:8081 -{% endhighlight %} +``` The version of the connected Brooklyn server may be viewed with the `version` command: -{% highlight text %} +```text $ br version 0.9.0-SNAPSHOT -{% endhighlight %} +``` ## Applications Deploy the application; on success the Id of the new application is displayed: -{% highlight text %} +```text $ br deploy webapp-policy.yaml Id: lmOcZbsT Name: WebCluster Status: In progress -{% endhighlight %} +``` The `application` command can be used to list a summary of all the running applications. After all of the entities have been started, the application status changes to `RUNNING`: -{% highlight text %} +```text $ br application Id Name Status Location YeEQHwgW AppCluster RUNNING CNTBOtjI lmOcZbsT WebCluster RUNNING CNTBOtjI -{% endhighlight %} +``` Further details of an application can be seen by using the ApplicationID or Name as a parameter for the `application` command: -{% highlight text %} +```text $ br application WebCluster Id: lmOcZbsT Name: WebCluster @@ -74,51 +74,51 @@ LocationId: CNTBOtjI LocationName: FixedListMachineProvisioningLocation:CNTB LocationSpec: byon LocationType: org.apache.brooklyn.location.byon.FixedListMachineProvisioningLocation -{% endhighlight %} +``` The configuration details of an application can be seen with the `config` command: -{% highlight text %} +```text $ br application WebCluster config Key Value camp.template.id TYWVroRz brooklyn.wrapper_app true -{% endhighlight %} +``` ## Entities The entities of an application can be viewed with the `entity` command: -{% highlight text %} +```text $ br app WebCluster entity Id Name Type xOcMooka WebApp org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster thHnLFkP WebDB org.apache.brooklyn.entity.database.mysql.MySqlNode -{% endhighlight %} +``` It is common for an entity to have child entities; these can be listed by providing an entity-scope for the `entity` command: -{% highlight text %} +```text $ br app WebCluster entity WebApp entity Id Name Type e5pWAiHf Cluster of TomcatServer org.apache.brooklyn.entity.webapp.DynamicWebAppCluster CZ8QUVgX NginxController:CZ8Q org.apache.brooklyn.entity.proxy.nginx.NginxController -{% endhighlight %} +``` or by using `-c` (or `--children`) flag with the `entity` command: -{% highlight text %} +```text $ br app WebCluster entity -c e5pWAiHf Id Name Type x0P2LRxZ quarantine org.apache.brooklyn.entity.group.QuarantineGroup QK6QjmrW TomcatServer:QK6Q org.apache.brooklyn.entity.webapp.tomcat.TomcatServer -{% endhighlight %} +``` As for applications, the configuration details of an entity can be seen with the `config` command: -{% highlight text %} +```text $ br app WebCluster entity thHnLFkP config Key Value install.unique_label MySqlNode_5.6.26 @@ -129,26 +129,26 @@ camp.plan.id db onbox.base.dir /home/vagrant/brooklyn-managed-processes onbox.base.dir.resolved true -{% endhighlight %} +``` The value of a single configuration item can be displayed by using the configuration key as a parameter for the `config` command: -{% highlight text %} +```text $ br app WebCluster entity thHnLFkP config datastore.creation.script.url https://bit.ly/brooklyn-visitors-creation-script -{% endhighlight %} +``` The value of a configuration item can be changed by using the `set` command: -{% highlight text %} +```text $ br app WebCluster entity thHnLFkP config datastore.creation.script.url set \"https://bit.ly/new-script\"; -{% endhighlight %} +``` ## Sensors The sensors associated with an application or entity can be listed with the `sensor` command: -{% highlight text %} +```text $ br app WebCluster entity CZ8QUVgX sensor Name Value download.addon.urls: {"stickymodule":"https://bitbucket.org/nginx-goodies/n @@ -207,28 +207,28 @@ softwareprocess.pid.file: softwareservice.provisioningLocation: {"type":"org.apache.brooklyn.api.location.Location","i d":"zhYBc6xt"} webapp.url: http://192.168.52.102:8000/ -{% endhighlight %} +``` Details for an individual sensor can be shown by providing the Sensor Name as a parameter to the `sensor` command: -{% highlight text %} +```text $ br app WebCluster entity CZ8QUVgX sensor service.state.expected running @ 1449314377781 / Sat Dec 05 11:19:37 GMT 2015 -{% endhighlight %} +``` ## Effectors The effectors for an application or entity can be listed with the `effector` command: -{% highlight text %} +```text $ br app WebCluster effector Name Description Parameters restart Restart the process/service represented by an entity start Start the process/service represented by an entity locations stop Stop the process/service represented by an entity -{% endhighlight %} +``` -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q effector Name Description Parameters deploy Deploys an archive ... @@ -239,57 +239,57 @@ restart Restart the process/service ... restartChildre start Start the process/service ... locations stop Stop the process/service ... stopProcessMode,stopMachineMode update Updates the entities ... -{% endhighlight %} +``` Details of an individual effector can be viewed by using the name as a parameter for the `effector` command: -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q effector update Name: update Description: Updates the entities configuration, and then forces reload of that configuration Parameters: -{% endhighlight %} +``` An effector can be invoked by using the `invoke` command with an effector-scope: -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q effector update invoke -{% endhighlight %} +``` Parameters can also be passed to the effector: -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q effector restart invoke -P restartChildren=true -{% endhighlight %} +``` If a parameter value is complex or spans multiple lines, it may be provided in a file and used like this: -{% highlight text %} +```text $ br app WebCluster effector start invoke -P [email protected] -{% endhighlight %} +``` Shortcut commands are available for the 3 standard effectors of `start`, `restart` and `stop`. These commands can be used directly with an app-scope or entity-scope: -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q restart $ br app WebCluster stop -{% endhighlight %} +``` ## Policies The policies associated with an application or entity can be listed with the `policy` command: -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q policy Id Name State VcZ0cfeO Controller targets tracker RUNNING -{% endhighlight %} +``` Details of an individual policy may be viewed by using the PolicyID as a parameter to the `policy` command: -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q policy VcZ0cfeO Name Value Description group DynamicWebAppClusterImpl{id=TpbkaK4D} group @@ -301,19 +301,19 @@ sensorsToTrack [Sensor: host.subnet.hostname Sensors of members (java.lang.Integer)] to this list, but that behaviour may be deleted in a subsequent release!) -{% endhighlight %} +``` ## Activities The activities for an application or entity may be listed with the `activity` command: -{% highlight text %} +```text $ br app WebCluster activity Id Task Submitted Status Streams Wb6GV5rt start Sat Dec 19 11:08:01 GMT 2015 Completed q2MbyyTo invoking start[locations] on 2 nodes Sat Dec 19 11:08:01 GMT 2015 Completed -{% endhighlight %} +``` -{% highlight text %} +```text $ br app WebCluster entity NginxController:CZ8Q activity Id Task Submitted Status Streams GVh0pyKG start Sun Dec 20 19:18:06 GMT 2015 Completed @@ -348,13 +348,13 @@ FJfPbNtp ssh: restarting NginxControllerImpl{i... Sun Dec 20 19:18:10 GMT 20 Xm1tjvKf update Sun Dec 20 19:18:40 GMT 2015 Completed Row67vfa reload Sun Dec 20 19:18:40 GMT 2015 Completed r8QZXlxJ ssh: restarting NginxControllerImpl{i... Sun Dec 20 19:18:40 GMT 2015 Completed env,stderr,stdin,stdout -{% endhighlight %} +``` The detail for an individual activity can be viewed by providing the ActivityID as a parameter to the `activity` command (an app-scope or entity-scope is not not needed for viewing the details of an activity): -{% highlight text %} +```text $ br activity tvZoNUTN Id: tvZoNUTN DisplayName: ssh: launching NginxControllerImpl{id=OxPUBk1p} @@ -372,13 +372,13 @@ Streams: stdin: 1133, stdout: 162, stderr: 0, env 0 DetailedStatus: "Completed after 1.05s Result: 0" -{% endhighlight %} +``` The activity command output shows whether any streams were associated with it. The streams and environment for an activity can be viewed with the commands `stdin`, `stdout`, `stderr` and `env`: -{% highlight text %} +```text $ br activity tvZoNUTN stdin export RUN_DIR="/home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p" mkdir -p $RUN_DIR @@ -393,20 +393,20 @@ do done echo "No explicit error launching nginx but couldn't find process by pid; continuing but may subsequently fail" cat /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/console | tee /dev/stderr -{% endhighlight %} +``` -{% highlight text %} +```text $ br activity tvZoNUTN stdout ./sbin/nginx PID TTY TIME CMD 6178 ? 00:00:00 nginx Executed /tmp/brooklyn-20151220-191808796-CaiI-launching_NginxControllerImpl_.sh, result 0 -{% endhighlight %} +``` The child activities of an activity may be listed by providing an activity-scope for the `activity` command: -{% highlight text %} +```text $ br activity OeZKwM5z Id: OeZKwM5z DisplayName: launch @@ -428,20 +428,20 @@ No return value (null)" $ br activity OeZKwM5z activity Id Task Submitted Status Streams tvZoNUTN ssh: launching NginxControllerImpl{id... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout -{% endhighlight %} +``` or by using the `-c` (or `--children`) flag with the `activity` command: -{% highlight text %} +```text $ br activity -c OeZKwM5z Id Task Submitted Status Streams tvZoNUTN ssh: launching NginxControllerImpl{id... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout -{% endhighlight %} +``` ## YAML Blueprint This is the YAML blueprint used for this document, based on the [web cluster](../../blueprints/clusters-and-policies.html) examples. -{% highlight text %} +```text name: WebCluster location: @@ -483,4 +483,4 @@ services: brooklyn.config: creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password") creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script -{% endhighlight %} +```
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/cli/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/cli/index.md b/guide/ops/cli/index.md index 1c79ce9..d618100 100644 --- a/guide/ops/cli/index.md +++ b/guide/ops/cli/index.md @@ -12,13 +12,13 @@ information on starting on a Brooklyn Server, refer to [Server CLI Reference](.. ## Obtaining the CLI tool -A selection of distributions of the CLI tool, `br`, are available to download from the download site {% if site.brooklyn-version contains 'SNAPSHOT' %} -[here](https://repository.apache.org/service/local/artifact/maven/redirect?r=snapshots&g=org.apache.brooklyn&a=brooklyn-client-cli&v={{site.brooklyn-version}}&c=bin&e=zip). +A selection of distributions of the CLI tool, `br`, are available to download from the download site {% if book.brooklyn-version %} +[here](https://repository.apache.org/service/local/artifact/maven/redirect?r=snapshots&g=org.apache.brooklyn&a=brooklyn-client-cli&v={{book.brooklyn-version}}&c=bin&e=zip). {% else %} here: -* [Windows](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-client-cli-windows.zip) -* [Linux](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-client-cli-linux.tar.gz) -* [OSX](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{site.brooklyn-version}}-client-cli-macosx.tar.gz) +* [Windows](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{book.brooklyn-version}}-client-cli-windows.zip) +* [Linux](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{book.brooklyn-version}}-client-cli-linux.tar.gz) +* [OSX](https://www.apache.org/dyn/closer.lua/brooklyn/apache-brooklyn-{{book.brooklyn-version}}-client-cli-macosx.tar.gz) {% endif %} Alternatively the CLI tool is available as an executable binary for many more platforms in the Apache Brooklyn @@ -38,4 +38,4 @@ or add the appropriate directory above to your path: ## Documentation -{% include list-children.html %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/configuration/brooklyn_cfg.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/brooklyn_cfg.md b/guide/ops/configuration/brooklyn_cfg.md index 11af09b..0c9895e 100644 --- a/guide/ops/configuration/brooklyn_cfg.md +++ b/guide/ops/configuration/brooklyn_cfg.md @@ -22,11 +22,11 @@ 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 %} +```properties brooklyn.webconsole.security.users=admin,bob brooklyn.webconsole.security.user.admin.password=AdminPassw0rd brooklyn.webconsole.security.user.bob.password=BobPassw0rd -{% endhighlight %} +``` In many cases, it is preferable instead to use an external credentials store such as LDAP. Information on configuring these is [below](#authentication). @@ -34,9 +34,9 @@ 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 %} +```properties brooklyn.webconsole.security.https.required=true -{% endhighlight %} +``` More information, including setting up a certificate, is described [further below](#https-configuration). @@ -46,21 +46,21 @@ More information, including setting up a certificate, is described [further belo 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 +This allows [externalized configuration]({{ book.path.guide }}/ops/externalized-configuration.html) to be used from `brooklyn.cfg`. For example: -{% highlight properties %} +```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 %} +```properties example.property=$brooklyn:literal("$brooklyn:myexample") -{% endhighlight %} +``` ## Java @@ -80,17 +80,17 @@ The default implementation, `ExplicitUsersSecurityProvider`, reads from a list o which should be specified as configuration parameters e.g. in `brooklyn.cfg`. This configuration could look like: -{% highlight properties %} +```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 %} +```bash brooklyn generate-password --user admin Enter password: @@ -101,7 +101,7 @@ 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 @@ -153,9 +153,9 @@ using a plug-in **Entitlement Manager**. This can be set globally with the property: -{% highlight properties %} +```properties brooklyn.entitlements.global=<class> -{% endhighlight %} +``` The default entitlement manager is one which responds to per-user entitlement rules, and understands: @@ -170,29 +170,29 @@ These keywords are also understood at the `global` level, so to grant full acces read-only access to `support`, limited access to `metrics` and regular access to `user` you can write: -{% highlight properties %} +```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 %} +```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). +[Java: Entitlements]({{ book.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" %}. +[EntitlementManager](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/api/mgmt/entitlement/EntitlementManager.html). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/configuration/cors.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/cors.md b/guide/ops/configuration/cors.md index ab2cd05..59dc01a 100644 --- a/guide/ops/configuration/cors.md +++ b/guide/ops/configuration/cors.md @@ -6,7 +6,7 @@ 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 [`org.apache.brooklyn.rest.filter.cors.cfg`](../paths.html) -{% highlight properties %} +```properties # Enables experimental support for Cross Origin Resource Sharing (CORS) filtering in Apache Brooklyn REST API. cors.enabled=true @@ -38,7 +38,7 @@ 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 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/configuration/https.md ---------------------------------------------------------------------- diff --git a/guide/ops/configuration/https.md b/guide/ops/configuration/https.md index 12515c5..98df1ee 100644 --- a/guide/ops/configuration/https.md +++ b/guide/ops/configuration/https.md @@ -11,11 +11,11 @@ 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 %} +```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. @@ -32,7 +32,7 @@ for example with `openssl`; this can then be converted into a Java keystore 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 %} +```bash % openssl pkcs12 -export -in cert.pem -inkey key.pem \ -out server.p12 -name "brooklyn" \ -CAfile ca.pem -caname root -chain -passout pass:"password" @@ -41,14 +41,14 @@ and then convert it into a keystore `keystore.jks` as follows: -deststorepass "password" -destkeypass "password" -destkeystore keystore.jks \ -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass "password" \ -alias "brooklyn" -{% endhighlight %} +``` ## HTTPS Configuration In [`org.ops4j.pax.web.cfg`](../paths.html) in the Brooklyn distribution root, un-comment the settings: -{% highlight properties %} +```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 @@ -56,7 +56,7 @@ 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 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/externalized-configuration.md ---------------------------------------------------------------------- diff --git a/guide/ops/externalized-configuration.md b/guide/ops/externalized-configuration.md index 545b012..a043061 100644 --- a/guide/ops/externalized-configuration.md +++ b/guide/ops/externalized-configuration.md @@ -21,7 +21,7 @@ of users, with `brooklyn.cfg` changing the behaviour depending on the deployment Here is the blueprint: -{% highlight yaml %} +```yaml name: MyApplication services: - type: brooklyn.entity.webapp.jboss.JBoss7Server @@ -36,7 +36,7 @@ services: - $brooklyn:external("servers", "postgresql") - $brooklyn:external("credentials", "postgresql-user") - $brooklyn:external("credentials", "postgresql-password") -{% endhighlight %} +``` You can see that when we are building up the JDBC URL, we are using the `external` function. This takes two parameters: the first is the name of the configuration supplier, the second is the name of a key that is stored by the configuration @@ -45,26 +45,26 @@ supplier. In this case we are using two different suppliers: `servers` to store Developers would add lines like this to the `brooklyn.cfg` file on their workstation: -{% highlight properties %} +```properties brooklyn.external.servers=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier brooklyn.external.servers.postgresql=127.0.0.1 brooklyn.external.credentials=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier 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.cfg`. Whereas in production, `brooklyn.cfg` might look like this: -{% highlight properties %} +```properties brooklyn.external.servers=org.apache.brooklyn.core.config.external.PropertiesFileExternalConfigSupplier brooklyn.external.servers.propertiesUrl=https://ops.example.com/servers.properties brooklyn.external.credentials=org.apache.brooklyn.core.config.external.vault.VaultAppIdExternalConfigSupplier brooklyn.external.credentials.endpoint=https://vault.example.com brooklyn.external.credentials.path=secret/enterprise-postgres brooklyn.external.credentials.appId=MyApp -{% endhighlight %} +``` In this case, the list of servers is stored in a properties file located on an Operations Department web server, and the credentials are stored in an instance of [Vault](https://www.vaultproject.io/). @@ -75,10 +75,10 @@ For demo purposes, there is a pre-defined external provider called This is used in some of the sample blueprints, referencing `$brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")`. The value used here can be overridden with the following in your `brooklyn.cfg`: -{% highlight properties %} +```properties brooklyn.external.brooklyn-demo-sample=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier brooklyn.external.brooklyn-demo-sample.hidden-brooklyn-password=new_password -{% endhighlight %} +``` ## Defining Suppliers @@ -94,11 +94,11 @@ implementations; see below for more details. Suppliers may require additional configuration options. These are given as additional properties in `brooklyn.cfg`: -{% highlight properties %} +```properties brooklyn.external.supplierName = className brooklyn.external.supplierName.firstConfig = value brooklyn.external.supplierName.secondConfig = value -{% endhighlight %} +``` ## Referring to External Configuration in Blueprints @@ -113,29 +113,29 @@ give the supplier the *key*. The returned value will be substituted into the blu You can use `$brooklyn:external` directly: -{% highlight yaml %} +```yaml name: MyApplication brooklyn.config: example: $brooklyn:external("supplier", "key") -{% endhighlight %} +``` or embed the `external` function inside another `$brooklyn` DSL function, such as `$brooklyn:formatString`: -{% highlight yaml %} +```yaml name: MyApplication brooklyn.config: example: $brooklyn:formatString("%s", external("supplier", "key")) -{% endhighlight %} +``` ## Referring to External Configuration in brooklyn.cfg The same blueprint language DSL can be used from `brooklyn.cfg`. For example: -{% highlight properties %} +```properties brooklyn.location.jclouds.aws-ec2.identity=$brooklyn:external("mysupplier", "aws-identity") brooklyn.location.jclouds.aws-ec2.credential=$brooklyn:external("mysupplier", "aws-credential") -{% endhighlight %} +``` ## Referring to External Configuration in Catalog Items @@ -165,10 +165,10 @@ Brooklyn ships with a number of external configuration suppliers ready to use. **InPlaceExternalConfigSupplier** embeds the configuration keys and values as properties inside `brooklyn.cfg`. For example: -{% highlight properties %} +```properties brooklyn.external.servers=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier brooklyn.external.servers.postgresql=127.0.0.1 -{% endhighlight %} +``` Then, a blueprint which referred to `$brooklyn:external("servers", "postgresql")` would receive the value `127.0.0.1`. @@ -179,16 +179,16 @@ file to respond to configuration lookups. Given this configuration: -{% highlight properties %} +```properties brooklyn.external.servers=org.apache.brooklyn.core.config.external.PropertiesFileExternalConfigSupplier brooklyn.external.servers.propertiesUrl=https://ops.example.com/servers.properties -{% endhighlight %} +``` This would cause the supplier to download the given URL. Assuming that the file contained this entry: -{% highlight properties %} +```properties postgresql=127.0.0.1 -{% endhighlight %} +``` Then, a blueprint which referred to `$brooklyn:external("servers", "postgresql")` would receive the value `127.0.0.1`. @@ -200,28 +200,28 @@ options that Vault provides. For *all* of the authentication methods, you must always set these properties in `brooklyn.cfg`: -{% highlight properties %} +```properties brooklyn.external.supplierName.endpoint=<Vault HTTP/HTTPs endpoint> brooklyn.external.supplierName.path=<path to a Vault object> -{% endhighlight %} +``` For example, if the path is set to `secret/brooklyn`, then attempting to retrieve the key `foo` would cause Brooklyn to retrieve the value of the `foo` key on the `secret/brooklyn` object. This value can be set using the Vault CLI like this: -{% highlight bash %} +```bash vault write secret/brooklyn foo=bar -{% endhighlight %} +``` #### Authentication by username and password The `userpass` plugin for Vault allows authentication with username and password. -{% highlight properties %} +```properties brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultUserPassExternalConfigSupplier brooklyn.external.supplierName.username=fred brooklyn.external.supplierName.password=s3kr1t -{% endhighlight %} +``` #### Authentication using App ID @@ -230,26 +230,26 @@ of the app. Typically the app ID would be known and shared, but user ID would be way. Brooklyn implements this by determining the MAC address of the server running Brooklyn (expressed as 12 lower case hexadecimal digits without separators) and passing this as the user ID. -{% highlight properties %} +```properties brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultAppIdExternalConfigSupplier brooklyn.external.supplierName.appId=MyApp -{% endhighlight %} +``` If you do not wish to use the MAC address as the user ID, you can override it with your own choice of user ID: -{% highlight properties %} +```properties brooklyn.external.supplierName.userId=server3.cluster2.europe -{% endhighlight %} +``` #### Authentication by fixed token If you have a fixed token string, then you can use the *VaultTokenExternalConfigSupplier* class and provide the token in `brooklyn.cfg`: -{% highlight properties %} +```properties brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultTokenExternalConfigSupplier brooklyn.external.supplierName.token=1091fc84-70c1-b266-b99f-781684dd0d2b -{% endhighlight %} +``` This supplier is suitable for "smoke testing" the Vault supplier using the Initial Root Token or similar. However it is not suitable for production use as it is inherently insecure - should the token be compromised, an attacker could @@ -261,10 +261,10 @@ other suppliers. Supplier implementations must conform to the brooklyn.config.external.ExternalConfigSupplier interface, which is very simple: -{% highlight java %} +```java String getName(); 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.cfg` as normal. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/gui/blueprints.md ---------------------------------------------------------------------- diff --git a/guide/ops/gui/blueprints.md b/guide/ops/gui/blueprints.md index 8c67f9b..561ed05 100644 --- a/guide/ops/gui/blueprints.md +++ b/guide/ops/gui/blueprints.md @@ -7,8 +7,6 @@ children: - { section: Launching from the Catalog, title: Launching from the Catalog } --- -{% include fields.md %} - ## Launching from a Blueprint @@ -27,18 +25,16 @@ Switch to the YAML tab and copy the blueprint below into the large text box. But *before* you submit it, modify the YAML to specify the location where the application will be deployed. -{% highlight yaml %} -{% readj _my-web-cluster.yaml %} -{% endhighlight %} +!CODEFILE "_my-web-cluster.yaml" Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather than AWS (updating with your own credentials): -{% highlight yaml %} +```yaml location: jclouds:softlayer: identity: ABCDEFGHIJKLMNOPQRST credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} +``` **NOTE**: See __[Locations](../locations)__ in the Operations section of the User Guide for instructions on setting up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file on disk rather than in the blueprint. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/gui/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/gui/index.md b/guide/ops/gui/index.md index 48bd620..ddc10f6 100644 --- a/guide/ops/gui/index.md +++ b/guide/ops/gui/index.md @@ -8,4 +8,4 @@ children: - policies.md --- -{% include list-children.html %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/gui/policies.md ---------------------------------------------------------------------- diff --git a/guide/ops/gui/policies.md b/guide/ops/gui/policies.md index eec033a..c0d1ba5 100644 --- a/guide/ops/gui/policies.md +++ b/guide/ops/gui/policies.md @@ -9,9 +9,7 @@ layout: website-normal To see an example of policy based management, please deploy the following blueprint (changing the location details as for the example shown earlier): -{% highlight yaml %} -{% readj _my-web-cluster2.yaml %} -{% endhighlight %} +!CODEFILE "_my-web-cluster2.yaml" The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/gui/running.md ---------------------------------------------------------------------- diff --git a/guide/ops/gui/running.md b/guide/ops/gui/running.md index b94f152..a3723cc 100644 --- a/guide/ops/gui/running.md +++ b/guide/ops/gui/running.md @@ -17,15 +17,15 @@ 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]({{ site.path.guide }}/ops/configuration/brooklyn_cfg.html) -* [Persistence]({{ site.path.guide }}/ops/persistence/) +* [Security]({{ book.path.guide }}/ops/configuration/brooklyn_cfg.html) +* [Persistence]({{ book.path.guide }}/ops/persistence/) Now start Brooklyn with the following command: -{% highlight bash %} -$ cd apache-brooklyn-{{ site.brooklyn.version }} +```bash +$ cd apache-brooklyn-{{ book.brooklyn.version }} $ bin/brooklyn launch -{% endhighlight %} +``` Please refer to the [Server CLI Reference](../server-cli-reference.html) for details of other possible command line options. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/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 8cd564b..cef1338 100644 --- a/guide/ops/high-availability/high-availability-supplemental.md +++ b/guide/ops/high-availability/high-availability-supplemental.md @@ -17,7 +17,7 @@ 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) +[Running Apache Brooklyn]({{ book.path.guide }}/start/running.html) On the first VM, which will be the master node, set the following configuration options in [`org.apache.brooklyn.osgilauncher.cfg`](../paths.html): @@ -27,11 +27,11 @@ On the first VM, which will be the master node, set the following configuration Then launch Brooklyn with: -{% highlight bash %} +```bash $ bin/start -{% endhighlight %} +``` -If you are using RPMs/deb to install, please see the [Running Apache Brooklyn]({{ site.path.guide }}/start/running.html) +If you are using RPMs/deb to install, please see the [Running Apache Brooklyn]({{ book.path.guide }}/start/running.html) documentation for the appropriate launch commands Once Brooklyn has launched, on the second VM, set the following configuration options in [`org.apache.brooklyn.osgilauncher.cfg`](../paths.html): @@ -42,9 +42,9 @@ Once Brooklyn has launched, on the second VM, set the following configuration op Then launch the standby Brooklyn with: -{% highlight bash %} +```bash $ bin/start -{% endhighlight %} +``` ### Failover When running as a HA standby node, each standby Brooklyn server (in this case there is only one standby) will check the shared persisted state @@ -101,19 +101,19 @@ To test a failover, you can simply terminate the process on the first VM and log output its PID to the file `pid.txt`; you can force an immediate (non-graceful) termination of the process by running the following command from the same directory from which you launched Brooklyn: -{% highlight bash %} +```bash $ kill -9 $(cat pid.txt) -{% endhighlight %} +``` It is also possiblity to check the high availability state of a running Brooklyn server using the following curl command: -{% highlight bash %} +```bash $ curl -k -u myusername:mypassword https://<ip-address>:8443/v1/server/ha/state -{% endhighlight %} +``` This will return one of the following states: -{% highlight bash %} +```bash "INITIALIZING" "STANDBY" @@ -123,20 +123,20 @@ This will return one of the following states: "FAILED" "TERMINATED" -{% endhighlight %} +``` Note: The quotation characters will be included in the reply To obtain information about all of the nodes in the cluster, run the following command against any of the nodes in the cluster: -{% highlight bash %} +```bash $ curl -k -u myusername:mypassword https://<ip-address>:8443/v1/server/ha/states -{% endhighlight %} +``` This will return a JSON document describing the Brooklyn nodes in the cluster. An example of two HA Brooklyn nodes is as follows (whitespace formatting has been added for clarity): -{% highlight yaml %} +```yaml { ownId: "XkJeXUXE", @@ -160,7 +160,7 @@ added for clarity): links: { } } -{% endhighlight %} +``` 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/18c248c5/guide/ops/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/index.md b/guide/ops/index.md index 29b5061..0807731 100644 --- a/guide/ops/index.md +++ b/guide/ops/index.md @@ -20,4 +20,4 @@ children: - troubleshooting/ --- -{% include list-children.html %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/logging.md ---------------------------------------------------------------------- diff --git a/guide/ops/logging.md b/guide/ops/logging.md index 41b6e4b..cdc506b 100644 --- a/guide/ops/logging.md +++ b/guide/ops/logging.md @@ -37,11 +37,11 @@ or in a new file included from this. The default `logback.xml` file references a collection of other log configuration files included in the Brooklyn jars. It is necessary to understand the source structure -in the [logback-includes]({{ site.brooklyn.url.git }}/logging/logback-includes) project. +in the [logback-includes]({{ book.brooklyn.url.git }}/logging/logback-includes) project. For example, to change the debug log inclusions, create a folder `brooklyn` under `conf` and create a file `logback-debug.xml` based on the -[brooklyn/logback-debug.xml]({{ site.brooklyn.url.git }}/logging/logback-includes/src/main/resources/brooklyn/logback-debug.xml) +[brooklyn/logback-debug.xml]({{ book.brooklyn.url.git }}/logging/logback-includes/src/main/resources/brooklyn/logback-debug.xml) from that project. @@ -75,6 +75,6 @@ which can then [feed its logs to Logstash](http://www.logstash.net/docs/1.4.2/in The following resources may be useful when configuring logging: -* The [logback-includes]({{ site.brooklyn.url.git }}/usage/logback-includes) project -* [Brooklyn Developer Guide]({{ site.path.guide }}/dev/tips/logging.html) logging tips +* The [logback-includes]({{ book.brooklyn.url.git }}/usage/logback-includes) project +* [Brooklyn Developer Guide]({{ book.path.guide }}/dev/tips/logging.html) logging tips * The [Logback Project](http://logback.qos.ch/) home page http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/persistence/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/persistence/index.md b/guide/ops/persistence/index.md index 52d47da..f63a16a 100644 --- a/guide/ops/persistence/index.md +++ b/guide/ops/persistence/index.md @@ -75,20 +75,20 @@ providers, see [jclouds](http://jclouds.apache.org/reference/providers/#blobstor To configure the Object Store, add the credentials to `brooklyn.cfg` such as: -{% highlight properties %} +```properties brooklyn.location.named.aws-s3-eu-west-1=aws-s3:eu-west-1 brooklyn.location.named.aws-s3-eu-west-1.identity=ABCDEFGHIJKLMNOPQRSTU brooklyn.location.named.aws-s3-eu-west-1.credential=abcdefghijklmnopqrstuvwxyz1234567890ab/c -{% endhighlight %} +``` or: -{% highlight properties %} +```properties brooklyn.location.named.softlayer-swift-ams01=jclouds:openstack-swift:https://ams01.objectstorage.softlayer.net/auth/v1.0 brooklyn.location.named.softlayer-swift-ams01.identity=ABCDEFGHIJKLM:myname brooklyn.location.named.softlayer-swift-ams01.credential=abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz12 brooklyn.location.named.softlayer-swift-ams01.jclouds.keystone.credential-type=tempAuthCredentials -{% endhighlight %} +``` Then edit the `persistenceLocation` to point at this object store: `softlayer-swift-ams01`. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/production-installation.md ---------------------------------------------------------------------- diff --git a/guide/ops/production-installation.md b/guide/ops/production-installation.md index 7825bdc..e6fe90a 100644 --- a/guide/ops/production-installation.md +++ b/guide/ops/production-installation.md @@ -3,8 +3,6 @@ layout: website-normal title: Production Installation --- -{% include fields.md %} - To install Apache Brooklyn on a production server: 1. [Set up the prerequisites](#prerequisites) @@ -16,7 +14,7 @@ To install Apache Brooklyn on a production server: This guide covers the basics. You may also wish to configure: -* [Logging]({{ site.path.guide }}/ops/logging.html) +* [Logging]({{ book.path.guide }}/ops/logging.html) * [Persistence](persistence/) * [High availability](high-availability/) @@ -28,45 +26,45 @@ Then configure the server as follows: * install Java JRE or JDK (version 8 or later) * enable "Java Cryptography Extension" (already enabled out of the box of OpenJDK installs) -* install an [SSH key]({{ site.path.guide }}/locations/index.html#ssh-keys), if not available -* if the "localhost" location will be used, enable [passwordless ssh login]({{ site.path.guide }}/locations/index.html#ssh-keys) +* install an [SSH key]({{ book.path.guide }}/locations/index.html#ssh-keys), if not available +* if the "localhost" location will be used, enable [passwordless ssh login]({{ book.path.guide }}/locations/index.html#ssh-keys) * create a `~/.brooklyn` directory on the host with `$ mkdir ~/.brooklyn` * check your `iptables` or other firewall service, making sure that incoming connections on port 8443 is not blocked -* check that the [linux kernel entropy]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) is sufficient -* check that the [ulimit values]({{ site.path.guide }}/ops/troubleshooting/increase-system-resource-limits.html) are sufficiently high +* check that the [linux kernel entropy]({{ book.path.guide }}/ops/troubleshooting/increase-entropy.html) is sufficient +* check that the [ulimit values]({{ book.path.guide }}/ops/troubleshooting/increase-system-resource-limits.html) are sufficiently high * ensure external libraries are up-to-date, including `nss` for SSL. * ensure the time is continually accurate, ideally by running a service like the [ntp daemon](http://www.ntp.org/). ### <a id="download"></a>Download Apache Brooklyn -Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download/). +Download Brooklyn and obtain a binary build as described on [the download page]({{book.path.website}}/download/). -{% if brooklyn_version contains 'SNAPSHOT' %} +{% if book.brooklyn-version %} Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different): {% else %} Expand the `tar.gz` archive: {% endif %} -{% if brooklyn_version contains 'SNAPSHOT' %} -{% highlight bash %} -% tar -zxf apache-brooklyn-dist-{{ site.brooklyn-stable-version }}-timestamp-dist.tar.gz -{% endhighlight %} +{% if book.brooklyn-version %} +```bash +% tar -zxf apache-brooklyn-dist-{{ book.brooklyn-stable-version }}-timestamp-dist.tar.gz +``` {% else %} -{% highlight bash %} -% tar -zxf apache-brooklyn-{{ site.brooklyn-stable-version }}-dist.tar.gz -{% endhighlight %} +```bash +% tar -zxf apache-brooklyn-{{ book.brooklyn-stable-version }}-dist.tar.gz +``` {% endif %} -This will create a `apache-brooklyn-{{ site.brooklyn-stable-version }}` folder. +This will create a `apache-brooklyn-{{ book.brooklyn-stable-version }}` folder. Let's setup some paths for easy commands. -{% highlight bash %} -% cd apache-brooklyn-{{ site.brooklyn-stable-version }} +```bash +% cd apache-brooklyn-{{ book.brooklyn-stable-version }} % BROOKLYN_DIR="$(pwd)" % export PATH=$PATH:$BROOKLYN_DIR/bin/ -{% endhighlight %} +``` ### <a id="configuring-properties"></a>Configuring brooklyn.cfg @@ -98,9 +96,9 @@ If you have a preferred catalog, simply replace that file. Launch Brooklyn in a disconnected session so it will remain running after you have logged out: -{% highlight bash %} +```bash % nohup bin/brooklyn launch > /dev/null 2&>1 & -{% endhighlight %} +``` Apache Brooklyn should now be running on port 8081 (or other port if so specified). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/requirements.md ---------------------------------------------------------------------- diff --git a/guide/ops/requirements.md b/guide/ops/requirements.md index aa63853..ab1d52b 100644 --- a/guide/ops/requirements.md +++ b/guide/ops/requirements.md @@ -36,7 +36,7 @@ There are three main consumers of disk space: * **Log files**: Brooklyn writes info and debug log files. By default, these are written to the local filesystem. This can be reconfigured to set the destination and to increase or decrease the detail in the logs. See the - [Logging]({{ site.path.guide }}/ops/logging.html) section for more details. + [Logging]({{ book.path.guide }}/ops/logging.html) section for more details. The Apache Brooklyn distribution itself, when unpacked, consumes approximately 75MB of disk space. This includes everything needed to run Brooklyn except for a @@ -57,7 +57,7 @@ therefore, can consume up to 2GB of disk space. In the default configuration of Brooklyn's `.tar.gz` and `.zip` distributions, logs are saved to the Brooklyn installation directory. You will most likely want -to [reconfigure Brooklyn's logging]({{ site.path.guide }}/ops/logging.html) to save logs to a location +to [reconfigure Brooklyn's logging]({{ book.path.guide }}/ops/logging.html) to save logs to a location elsewhere. In the `.rpm` and `.deb` packaging, logging files will be located under `/var/log`. You can further reconfiguring the logging detail level and log rotation according to your organisation's policy. @@ -109,9 +109,9 @@ It is normally recommended that Brooklyn run as a non-root user with keys instal ### Linux Kernel Entropy -Check that the [linux kernel entropy]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) is sufficient. +Check that the [linux kernel entropy]({{ book.path.guide }}/ops/troubleshooting/increase-entropy.html) is sufficient. ### System Resource Limits -Check that the [ulimit values]({{ site.path.guide }}/ops/troubleshooting/increase-system-resource-limits.html) are sufficiently high. +Check that the [ulimit values]({{ book.path.guide }}/ops/troubleshooting/increase-system-resource-limits.html) are sufficiently high. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/server-cli-reference.md ---------------------------------------------------------------------- diff --git a/guide/ops/server-cli-reference.md b/guide/ops/server-cli-reference.md index f30fa06..b9f4377 100644 --- a/guide/ops/server-cli-reference.md +++ b/guide/ops/server-cli-reference.md @@ -10,9 +10,9 @@ already running Brooklyn Server, refer to [Client CLI Reference](cli/index.html) To launch Brooklyn, from the directory where Brooklyn is unpacked, run: -{% highlight bash %} +```bash % nohup bin/brooklyn launch > /dev/null 2>&1 & -{% endhighlight %} +``` With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/), listening on all network interfaces. No credentials are required by default. For a production @@ -27,7 +27,7 @@ You may wish to [add Brooklyn to your path](#path-setup); assuming you've done this, to get information the supported CLI options at any time, just run `brooklyn help`: -{% highlight bash %} +```bash % bin/brooklyn help usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>] @@ -38,7 +38,7 @@ The most commonly used brooklyn commands are: launch Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath. See 'brooklyn help <command>' for more information on a specific command. -{% endhighlight %} +``` It is important that Brooklyn is launched with either `nohup ... &` or `... & disown`, to ensure it keeps running after the shell terminates. @@ -54,10 +54,10 @@ The Server CLI arguments for [persistence and HA](persistence/) and the [catalog In order to have easy access to the server cli it is useful to configure the PATH environment variable to also point to the cli's bin directory: -{% highlight bash %} +```bash BROOKLYN_HOME=/path/to/brooklyn/ export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/ -{% endhighlight %} +``` ### Memory Usage http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/starting-stopping-monitoring.md ---------------------------------------------------------------------- diff --git a/guide/ops/starting-stopping-monitoring.md b/guide/ops/starting-stopping-monitoring.md index 906c11b..2604b30 100644 --- a/guide/ops/starting-stopping-monitoring.md +++ b/guide/ops/starting-stopping-monitoring.md @@ -25,9 +25,9 @@ files. To launch Brooklyn, from the directory where Brooklyn is unpacked, run: -{% highlight bash %} +```bash % bin/start -{% endhighlight %} +``` With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/), listening on all network interfaces. No credentials are required by default. It is strongly @@ -43,7 +43,7 @@ To stop Brooklyn, from the directory where Brooklyn is unpacked, run: For example: -{% highlight bash %} +```bash % bin/stop {% endhighlight bash %} @@ -65,11 +65,11 @@ For example, here is a fragment of a `monitrc` file as used by [Monit](https://mmonit.com/monit/), for a Brooklyn `.tar.gz` distribution unpacked and installed at `/opt/apache-brooklyn`: -{% highlight text %} +```text check process apachebrooklyn with pidfile /opt/apache-brooklyn/pid_java start program = "/bin/bash -c '/opt/apache-brooklyn/bin/brooklyn launch --persist auto & disown'" with timeout 10 seconds stop program = "/bin/bash -c 'kill $( cat /opt/apache-brooklyn/pid_java )'" -{% endhighlight %} +``` In addition to monitoring the Brooklyn process itself, you will almost certainly want to monitor resource usage of Brooklyn. In particular, please see the http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/connectivity.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/connectivity.md b/guide/ops/troubleshooting/connectivity.md index 0ec7139..a0c37e0 100644 --- a/guide/ops/troubleshooting/connectivity.md +++ b/guide/ops/troubleshooting/connectivity.md @@ -4,4 +4,4 @@ title: Troubleshooting Server Connectivity Issues in the Cloud toc: /guide/toc.json --- -{% readj _connectivity.md %} +{% include '_connectivity.md' %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/deployment.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/deployment.md b/guide/ops/troubleshooting/deployment.md index 67d28c8..210bc2c 100644 --- a/guide/ops/troubleshooting/deployment.md +++ b/guide/ops/troubleshooting/deployment.md @@ -18,16 +18,16 @@ section is missing. An error like the one shown below means that the given entity type (in this case com.acme.Foo) is not in the catalog or on the classpath: -{% highlight bash %} +```bash Deployment plan item Service[name=<null>,description=<null>,serviceType=com.acme.Foo,characteristics=[],customAttributes={}] cannot be matched -{% endhighlight %} +``` An error like the one shown below means that the given location (in this case aws-ec3) was unknown: -{% highlight bash %} +```bash Illegal parameter for 'location' (aws-ec3); not resolvable: java.util.NoSuchElementException: Unknown location 'aws-ec3': either this location is not recognised or there is a problem with location resolver configuration -{% endhighlight %} +``` This means it does not match any of the named locations in brooklyn.properties, nor any of the clouds enabled in the jclouds support, nor any of the locations added dynamically through the catalog API. @@ -100,15 +100,15 @@ includes the ssl library. To fix this on CentOS, run: -{% highlight bash %} +```bash sudo yum upgrade nss -{% endhighlight %} +``` For a discussion of investigating this kind of issue, see this [Backslasher blog](http://blog.backslasher.net/java-ssl-crash.html). The full stacktrace is shown below: -{% highlight java %} +```java Caused by: javax.net.ssl.SSLException: java.security.ProviderException: java.security.KeyException at sun.security.ssl.Alerts.getSSLException(Alerts.java:208) at sun.security.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1949) @@ -142,7 +142,7 @@ Caused by: java.security.KeyException at sun.security.ec.ECKeyPairGenerator.generateECKeyPair(Native Method) at sun.security.ec.ECKeyPairGenerator.generateKeyPair(ECKeyPairGenerator.java:128) ... 83 more -{% endhighlight %} +``` ## Timeout Waiting For Service-Up @@ -162,16 +162,16 @@ If you receive an error message similar to the one below when provisioning a VM, You can workaround the issue by explicitly setting the user that Brooklyn should use to login to the VM (typically the OS default user). -{% highlight bash %} +```bash error acquiring SFTPClient() (out of retries - max 50) Invalid packet: indicated length too large java.lang.IllegalStateException Invalid packet: indicated length too large -{% endhighlight %} +``` An example of how to explicitly set the user is shown below (when defining a Location) by using 'loginUser': -{% highlight yaml %} +```yaml brooklyn.locations: - type: jclouds:aws-ec2 brooklyn.config: @@ -180,7 +180,7 @@ brooklyn.locations: identity: <add> credential: <add> loginUser: centos -{% endhighlight %} +``` ## SSLException close_notify Exception http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/detailed-support-report.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/detailed-support-report.md b/guide/ops/troubleshooting/detailed-support-report.md index c41ebcb..9626e89 100644 --- a/guide/ops/troubleshooting/detailed-support-report.md +++ b/guide/ops/troubleshooting/detailed-support-report.md @@ -9,7 +9,7 @@ collecting the following information. See [Brooklyn Slow or Unresponse](slow-unresponsive.html) docs for details of these commands. -{% highlight bash %} +```bash BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java) REPORT_DIR=/tmp/brooklyn-report/ @@ -34,10 +34,10 @@ done grep "brooklyn gc" ${DEBUG_LOG} > ${REPORT_DIR}/brooklyn-gc.txt grep "events for subscriber" ${DEBUG_LOG} > ${REPORT_DIR}/events-for-subscriber.txt tar czf brooklyn-report.tgz ${REPORT_DIR} -{% endhighlight %} +``` Also consider providing your log files and persisted state, though extreme care should be taken if these might contain cloud or machine credentials (especially if -[Externalised Configuration]({{ site.path.guide }}/ops/externalized-configuration.html) +[Externalised Configuration]({{ book.path.guide }}/ops/externalized-configuration.html) is not being used for credential storage). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/going-deep-in-java-and-logs.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/going-deep-in-java-and-logs.md b/guide/ops/troubleshooting/going-deep-in-java-and-logs.md index 8a66ce0..173d48d 100644 --- a/guide/ops/troubleshooting/going-deep-in-java-and-logs.md +++ b/guide/ops/troubleshooting/going-deep-in-java-and-logs.md @@ -14,7 +14,7 @@ a bash script. First let's take a look at the `customize()` method of the Tomcat server blueprint: -{% highlight java %} +```java @Override public void customize() { newScript(CUSTOMIZING) @@ -34,28 +34,28 @@ public void customize() { getEntity().deployInitialWars(); } -{% endhighlight %} +``` Here we can see that it's running a script to create four directories before continuing with the customization. Let's introduce an error by changing `mkdir` to `mkrid`: -{% highlight java %} +```java newScript(CUSTOMIZING) .body.append("mkrid -p conf logs webapps temp") // `mkdir` changed to `mkrid` .failOnNonZeroResultCode() .execute(); -{% endhighlight %} +``` Now let's try deploying this using the following YAML: -{% highlight yaml %} +```yaml name: Tomcat failure test location: localhost services: - type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer -{% endhighlight %} +``` Shortly after deployment, the entity fails with the following error: @@ -72,9 +72,9 @@ that particular task, including its sub-tasks. We can eventually get to the spec By clicking on the `stderr` link, we can see the script failed with the following error: -{% highlight console %} +```console /tmp/brooklyn-20150721-132251052-l4b9-customizing_TomcatServerImpl_i.sh: line 10: mkrid: command not found -{% endhighlight %} +``` This tells us *what* went wrong, but doesn't tell us *where*. In order to find that, we'll need to look at the stack trace that was logged when the exception was thrown. @@ -82,7 +82,7 @@ stack trace that was logged when the exception was thrown. It's always worth looking at the Detailed Status section as sometimes this will give you the information you need. In this case, the stack trace is limited to the thread that was used to execute the task that ran the script: -{% highlight console %} +```console Failed after 40ms STDERR @@ -103,7 +103,7 @@ java.lang.IllegalStateException: Execution failed, invalid result 127 for custom at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615) at java.lang.Thread.run(Thread.java:745) -{% endhighlight %} +``` In order to find the exception, we'll need to look in Brooklyn's debug log file. By default, the debug log file is named `brooklyn.debug.log`. Usually the easiest way to navigate the log file is to use `less`, e.g. @@ -117,7 +117,7 @@ performing a reverse-lookup), simply press `n` In this case, the `?Tomcat` search takes us directly to the full stack trace (Only the last part of the trace is shown here): -{% highlight console %} +```console ... at com.google.common.util.concurrent.ForwardingFuture.get(ForwardingFuture.java:63) ~[guava-17.0.jar:na] at org.apache.brooklyn.core.util.task.BasicTask.get(BasicTask.java:343) ~[classes/:na] at org.apache.brooklyn.core.util.task.BasicTask.getUnchecked(BasicTask.java:352) ~[classes/:na] @@ -144,15 +144,15 @@ Caused by: java.lang.IllegalStateException: Execution failed, invalid result 127 at org.apache.brooklyn.entity.software.base.lifecycle.ScriptHelper$8.call(ScriptHelper.java:289) ~[classes/:na] at org.apache.brooklyn.entity.software.base.lifecycle.ScriptHelper$8.call(ScriptHelper.java:287) ~[classes/:na] ... 6 common frames omitted -{% endhighlight %} +``` Brooklyn's use of tasks and helper classes can make the stack trace a little harder than usual to follow, but a good place to start is to look through the stack trace for the node's implementation or ssh driver classes (usually named `FooNodeImpl` or `FooSshDriver`). In this case we can see the following: -{% highlight console %} +```console at org.apache.brooklyn.entity.webapp.tomcat.TomcatSshDriver.customize(TomcatSshDriver.java:72) ~[classes/:na] -{% endhighlight %} +``` Combining this with the error message of `mkrid: command not found` we can see that indeed `mkdir` has been misspelled `mkrid` on line 72 of `TomcatSshDriver.java`. @@ -165,7 +165,7 @@ a failure in a non-script related part of the code. We'll use the `customize()` but this time, we'll correct the spelling of 'mkdir' and add a line that attempts to copy a nonexistent resource to the remote server: -{% highlight java %} +```java newScript(CUSTOMIZING) .body.append("mkdir -p conf logs webapps temp") @@ -176,7 +176,7 @@ copyTemplate(entity.getConfig(TomcatServer.SERVER_XML_RESOURCE), Os.mergePaths(g copyTemplate(entity.getConfig(TomcatServer.WEB_XML_RESOURCE), Os.mergePaths(getRunDir(), "conf", "web.xml")); copyTemplate("classpath://nonexistent.xml", Os.mergePaths(getRunDir(), "conf", "nonexistent.xml")); // Resource does not exist! -{% endhighlight %} +``` Let's deploy this using the same YAML from above. Here's the resulting error in the Brooklyn debug console: @@ -185,7 +185,7 @@ Let's deploy this using the same YAML from above. Here's the resulting error in Again, this tells us *what* the error is, but we need to find *where* the code is that attempts to copy this file. In this case it's shown in the Detailed Status section, and we don't need to go to the log file: -{% highlight console %} +```console Failed after 221ms: Error getting resource 'classpath://nonexistent.xml' for TomcatServerImpl{id=PVZxDKU1}: java.io.IOException: Error accessing classpath://nonexistent.xml: java.io.IOException: nonexistent.xml not found on classpath @@ -213,7 +213,7 @@ Caused by: java.io.IOException: nonexistent.xml not found on classpath at org.apache.brooklyn.core.util.ResourceUtils.getResourceFromUrl(ResourceUtils.java:230) ... 14 more -{% endhighlight %} +``` Looking for `Tomcat` in the stack trace, we can see in this case the problem lies at line 79 of `TomcatSshDriver.java` @@ -228,9 +228,9 @@ the entity fails to start. We can simulate this type of failure by launching Tomcat with an invalid configuration file. As seen in the previous examples, Brooklyn copies two xml configuration files to the server: `server.xml` and `web.xml` -The first few non-comment lines of `server.xml` are as follows (you can see the full file [here]({{ site.brooklyn.url.git }}/software/webapp/src/main/resources/org/apache/brooklyn/entity/webapp/tomcat/server.xml)): +The first few non-comment lines of `server.xml` are as follows (you can see the full file [here]({{ book.brooklyn.url.git }}/software/webapp/src/main/resources/org/apache/brooklyn/entity/webapp/tomcat/server.xml)): -{% highlight xml %} +```xml <Server port="${driver.shutdownPort?c}" shutdown="SHUTDOWN"> <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /> @@ -240,7 +240,7 @@ The first few non-comment lines of `server.xml` are as follows (you can see the Let's add an unmatched XML element, which will make this XML file invalid: -{% highlight xml %} +```xml <Server port="${driver.shutdownPort?c}" shutdown="SHUTDOWN"> <unmatched-element> <!-- This is invalid XML as we won't add </unmatched-element> --> @@ -260,15 +260,15 @@ with `Timeout waiting for SERVICE_UP`: If we drill down into the tasks in the `Activities` tab, we can see that all of the installation and launch tasks completed successfully, and stdout of the `launch` script is as follows: -{% highlight console %} +```console Executed /tmp/brooklyn-20150721-153049139-fK2U-launching_TomcatServerImpl_id_.sh, result 0 -{% endhighlight %} +``` The task that failed was the `post-start` task, and the stack trace from the Detailed Status section is as follows: -{% highlight console %} +```console Failed after 5m 1s: Timeout waiting for SERVICE_UP from TomcatServerImpl{id=BUHgQeOs} @@ -286,7 +286,7 @@ java.lang.IllegalStateException: Timeout waiting for SERVICE_UP from TomcatServe at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615) at java.lang.Thread.run(Thread.java:745) -{% endhighlight %} +``` This doesn't really tell us what we need to know, and looking in the `brooklyn.debug.log` file yields no further clues. The key here is the error message `Timeout waiting for SERVICE_UP`. After running the installation and @@ -300,12 +300,12 @@ The first thing we need to do is to find out how Brooklyn determines the health often implemented in the `isRunning()` method in the entity's ssh driver. Tomcat's implementation of `isRunning()` is as follows: -{% highlight java %} +```java @Override public boolean isRunning() { return newScript(MutableMap.of(USE_PID_FILE, "pid.txt"), CHECK_RUNNING).execute() == 0; } -{% endhighlight %} +``` The `newScript` method has conveniences for default scripts to check if a process is running based on its PID. In this case, it will look for Tomcat's PID in the `pid.txt` file and check if the PID is the PID of a running process @@ -315,15 +315,15 @@ By default, the pid file is located in the run directory of the entity. You can directory by looking at the `run.dir` sensor. In this case it is `/tmp/brooklyn-martin/apps/jIzIHXtP/entities/TomcatServer_BUHgQeOs`. To find the pid, you simply cat the pid.txt file in this directory: -{% highlight console %} +```console $ cat /tmp/brooklyn-martin/apps/jIzIHXtP/entities/TomcatServer_BUHgQeOs/pid.txt 73714 -{% endhighlight %} +``` In this case, the PID in the file is 73714. You can then check if the process is running using `ps`. You can also pipe the output to `fold` so the full launch command is visible: -{% highlight console %} +```console $ ps -p 73714 | fold -w 120 PID TTY TIME CMD @@ -338,23 +338,23 @@ in/apps/jIzIHXtP/entities/TomcatServer_BUHgQeOs -Dcatalina.home=/tmp/brooklyn-ma -tomcat-7.0.56 -Djava.io.tmpdir=/tmp/brooklyn-martin/apps/jIzIHXtP/entities/TomcatServer_BUHgQeOs/temp org.apache.catali na.startup.Bootstrap start -{% endhighlight %} +``` This confirms that the process is running. The next thing we can look at is the `service.notUp.indicators` sensor. This reads as follows: -{% highlight json %} +```json {"service.process.isRunning":"The software process for this entity does not appear to be running"} -{% endhighlight %} +``` This confirms that the problem is indeed due to the `service.process.isRunning` sensor. We assumed earlier that this was set by the `isRunning()` method in `TomcatSshDriver.java`, but this isn't always the case. The `service.process.isRunning` sensor is wired up by the `connectSensors()` method in the node's implementation class, in this case `TomcatServerImpl.java`. Tomcat's implementation of `connectSensors()` is as follows: -{% highlight java %} +```java @Override public void connectSensors() { @@ -396,7 +396,7 @@ public void connectSensors() { } } -{% endhighlight %} +``` We can see here that if jmx is not enabled, the method will call `connectServiceUpIsRunning()` which will use the default PID-based method of determining if a process is running. However, as JMX *is* running, the `service.process.isRunning` @@ -404,12 +404,12 @@ sensor (denoted here by the `SERVICE_PROCESS_IS_RUNNING` variable) is set to tru `stateName` JMX attribute equals `STARTED`. We can see from the previous call to `.pollAttribute` that this attribute is also published to the `CONNECTOR_STATUS` sensor. The `CONNECTOR_STATUS` sensor is defined as follows: -{% highlight java %} +```java AttributeSensor<String> CONNECTOR_STATUS = new BasicAttributeSensor<String>(String.class, "webapp.tomcat.connectorStatus", "Catalina connector state name"); -{% endhighlight %} +``` Let's go back to the Brooklyn debug console and look for the `webapp.tomcat.connectorStatus`: @@ -429,11 +429,11 @@ Let's assume that we've checked that and they're all open. There is still one mo Still on the `Sensors` tab, let's take a look at the `log.location` sensor: -{% highlight console %} +```console /tmp/brooklyn-martin/apps/c3bmrlC3/entities/TomcatServer_C1TAjYia/logs/catalina.out -{% endhighlight %} +``` This is the location of Tomcat's own log file. The location of the log file will differ from process to process and when writing a custom entity you will need to check the software's own documentation. If your blueprint's @@ -444,7 +444,7 @@ automatically be published to the `log.location` sensor. Otherwise, you can publ **Note:** The log file will be on the server to which you have deployed Tomcat, and not on the Brooklyn server. Let's take a look in the log file: -{% highlight console %} +```console $ less /tmp/brooklyn-martin/apps/c3bmrlC3/entities/TomcatServer_C1TAjYia/logs/catalina.out @@ -479,6 +479,6 @@ WARNING: Catalina.start using conf/server.xml: The element type "unmatched-eleme Jul 21, 2015 4:12:12 PM org.apache.catalina.startup.Catalina start SEVERE: Cannot start server. Server instance is not configured. -{% endhighlight %} +``` As expected, we can see here that the `unmatched-element` element has not been terminated in the `server.xml` file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/increase-entropy.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/increase-entropy.md b/guide/ops/troubleshooting/increase-entropy.md index 6fc6f8d..a5989b1 100644 --- a/guide/ops/troubleshooting/increase-entropy.md +++ b/guide/ops/troubleshooting/increase-entropy.md @@ -10,9 +10,9 @@ A lack of entropy can cause random number generation to be extremely slow. This results in tasks like ssh to also be extremely slow. One can check the available entropy on a machine by running the command: -{% highlight bash %} +```bash cat /proc/sys/kernel/random/entropy_avail -{% endhighlight %} +``` It should be a value above 2000. @@ -25,16 +25,16 @@ to the managed entities. You can install and configure `rng-tools`, or just use If you are using a RHEL 6 based OS: -{% highlight bash %} +```bash sudo -i yum -y -q install rng-tools echo "EXTRAOPTIONS=\"-r /dev/urandom\"" | cat >> /etc/sysconfig/rngd /etc/init.d/rngd start -{% endhighlight %} +``` If you are using a RHEL 7 or a systemd based system: -{% highlight bash %} +```bash sudo yum -y -q install rng-tools # Configure rng to use /dev/urandom @@ -44,26 +44,26 @@ sudo vi /etc/systemd/system/multi-user.target.wants/rngd.service sudo systemctl daemon-reload sudo systemctl start rngd -{% endhighlight %} +``` If you are using a Debian-based OS: -{% highlight bash %} +```bash sudo -i apt-get -y install rng-tools echo "HRNGDEVICE=/dev/urandom" | cat >> /etc/default/rng-tools /etc/init.d/rng-tools start -{% endhighlight %} +``` ### Using /dev/urandom You can also just `mv /dev/random` then create it again linked to `/dev/urandom`: -{% highlight bash %} +```bash sudo mv /dev/random /dev/random-real sudo ln -s /dev/urandom /dev/random -{% endhighlight %} +``` Notice! If you map `/dev/random` to use `/dev/urandom` you will need to restart the Apache Brooklyn java process in order for the change to take place. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/index.md b/guide/ops/troubleshooting/index.md index 331e267..670e666 100644 --- a/guide/ops/troubleshooting/index.md +++ b/guide/ops/troubleshooting/index.md @@ -15,4 +15,4 @@ children: - { path: memory-usage.md, title: Monitoring Memory Usage } --- -{% include list-children.html %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/overview.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/overview.md b/guide/ops/troubleshooting/overview.md index ac00aeb..172d608 100644 --- a/guide/ops/troubleshooting/overview.md +++ b/guide/ops/troubleshooting/overview.md @@ -82,7 +82,7 @@ For example, it can show the exception stack trace in the thread that was execut ## Log Files Brooklyn's logging is configurable, for the files created, the logging levels, etc. -See [Logging docs]({{ site.path.guide }}/ops/logging.html). +See [Logging docs]({{ book.path.guide }}/ops/logging.html). With out-of-the-box logging, `brooklyn.info.log` and `brooklyn.debug.log` files are created. These are by default rolling log files: when the log reaches a given size, it is compressed and a new log file is started. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/troubleshooting/slow-unresponsive.md ---------------------------------------------------------------------- diff --git a/guide/ops/troubleshooting/slow-unresponsive.md b/guide/ops/troubleshooting/slow-unresponsive.md index 6551759..b25f3f3 100644 --- a/guide/ops/troubleshooting/slow-unresponsive.md +++ b/guide/ops/troubleshooting/slow-unresponsive.md @@ -14,7 +14,7 @@ Possible reasons include: * SSH'ing is very slow due (e.g. due to lack of entropy) * Out of disk space -See [Brooklyn Requirements]({{ site.path.guide }}/ops/requirements.html) for details of server +See [Brooklyn Requirements]({{ book.path.guide }}/ops/requirements.html) for details of server requirements. @@ -29,16 +29,16 @@ other platforms. To display system information, run: -{% highlight bash %} +```bash uname -a -{% endhighlight %} +``` To show details of the CPU and memory available to the machine, run: -{% highlight bash %} +```bash cat /proc/cpuinfo cat /proc/meminfo -{% endhighlight %} +``` #### User Limits @@ -46,19 +46,19 @@ cat /proc/meminfo To display information about user limits, run the command below (while logged in as the same user who runs Brooklyn): -{% highlight bash %} +```bash ulimit -a -{% endhighlight %} +``` If Brooklyn is run as a different user (e.g. with user name "adalovelace"), then instead run: -{% highlight bash %} +```bash ulimit -a -u adalovelace -{% endhighlight %} +``` Of particular interest is the limit for "open files". -See [Increase System Resource Limits]({{ site.path.guide }}/ops/troubleshooting/increase-system-resource-limits.html) +See [Increase System Resource Limits]({{ book.path.guide }}/ops/troubleshooting/increase-system-resource-limits.html) for more information. @@ -68,9 +68,9 @@ The command below will list the disk size for each partition, including the amou available. If the Brooklyn base directory, persistence directory or logging directory are close to 0% available, this can cause serious problems: -{% highlight bash %} +```bash df -h -{% endhighlight %} +``` #### CPU and Memory Usage @@ -79,33 +79,33 @@ To view the CPU and memory usage of all processes, and of the machine as a whole `top` command. This runs interactively, updating every few seconds. To collect the output once (e.g. to share diagnostic information in a bug report), run: -{% highlight bash %} +```bash top -n 1 -b > top.txt -{% endhighlight %} +``` #### File and Network Usage To count the number of open files for the Brooklyn process (which includes open socket connections): -{% highlight bash %} +```bash BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java) lsof -p $BROOKLYN_PID | wc -l -{% endhighlight %} +``` To count (or view the number of "established" internet connections, run: -{% highlight bash %} +```bash netstat -an | grep ESTABLISHED | wc -l -{% endhighlight %} +``` #### Linux Kernel Entropy A lack of entropy can cause random number generation to be extremely slow. This can cause tasks like ssh to also be extremely slow. See -[linux kernel entropy]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) +[linux kernel entropy]({{ book.path.guide }}/ops/troubleshooting/increase-entropy.html) for details of how to work around this. @@ -117,14 +117,14 @@ To get memory and thread usage for the Brooklyn (Java) process, two useful tools and `jmap`. These require the "development kit" to also be installed (e.g. `yum install java-1.8.0-openjdk-devel`). Some useful commands are shown below: -{% highlight bash %} +```bash BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java) jstack $BROOKLYN_PID jmap -histo:live $BROOKLYN_PID jmap -heap $BROOKLYN_PID -{% endhighlight %} +``` #### Runnable Threads @@ -134,14 +134,14 @@ script is a convenient light-weight way to quickly see which threads of a runnin server are attempting to consume the CPU. It filters the output of `jstack`, to show only the "really-runnable" threads (as opposed to those that are blocked). -{% highlight bash %} +```bash BROOKLYN_HOME=/home/users/brooklyn/apache-brooklyn-0.9.0-bin BROOKLYN_PID=$(cat $BROOKLYN_HOME/pid_java) curl -O https://raw.githubusercontent.com/apache/brooklyn-dist/master/scripts/jstack-active.sh jstack-active $BROOKLYN_PID -{% endhighlight %} +``` #### Profiling @@ -157,14 +157,14 @@ appropriate for a production server. If the Brooklyn Server was originally run to allow a remote debugger to connect (strongly discouraged in production!), then this provides a convenient way to investigate why Brooklyn is being slow or unresponsive. See the Debugging Tips in the -tip [Debugging Remote Brooklyn]({{ site.path.guide }}/dev/tips/debugging-remote-brooklyn.html) -and the [IDE docs]({{ site.path.guide }}/dev/env/ide/) for more information. +tip [Debugging Remote Brooklyn]({{ book.path.guide }}/dev/tips/debugging-remote-brooklyn.html) +and the [IDE docs]({{ book.path.guide }}/dev/env/ide/) for more information. ## Log Files Apache Brooklyn will by default create brooklyn.info.log and brooklyn.debug.log files. See the -[Logging]({{ site.path.guide }}/ops/logging.html) docs for more information. +[Logging]({{ book.path.guide }}/ops/logging.html) docs for more information. The following are useful log messages to search for (e.g. using `grep`). Note the wording of these messages (or their very presence) may change in future version of Brooklyn. @@ -174,22 +174,22 @@ these messages (or their very presence) may change in future version of Brooklyn The lines below are commonly logged, and can be useful to search for when finding the start of a section of logging. -{% highlight text %} +```text 2016-05-30 17:05:51,458 INFO o.a.b.l.BrooklynWebServer [main]: Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war 2016-05-30 17:06:04,098 INFO o.a.b.c.m.h.HighAvailabilityManagerImpl [main]: Management node tF3GPvQ5 running as HA MASTER autodetected 2016-05-30 17:06:08,982 INFO o.a.b.c.m.r.InitialFullRebindIteration [brooklyn-execmanager-rvpnFTeL-0]: Rebinding from /home/compose/compose-amp-state/brooklyn-persisted-state/data for master rvpnFTeL... 2016-05-30 17:06:11,105 INFO o.a.b.c.m.r.RebindIteration [brooklyn-execmanager-rvpnFTeL-0]: Rebind complete (MASTER) in 2s: 19 apps, 54 entities, 50 locations, 46 policies, 704 enrichers, 0 feeds, 160 catalog items -{% endhighlight %} +``` #### Memory Usage The debug log includes (every minute) a log statement about the memory usage and task activity. For example: -{% highlight text %} +```text 2016-05-27 12:20:19,395 DEBUG o.a.b.c.m.i.BrooklynGarbageCollector [brooklyn-gc]: brooklyn gc (before) - using 328 MB / 496 MB memory (5.58 kB soft); 69 threads; storage: {datagrid={size=7, createCount=7}, refsMapSize=0, listsMapSize=0}; tasks: 10 active, 33 unfinished; 78 remembered, 1696906 total submitted) 2016-05-27 12:20:19,395 DEBUG o.a.b.c.m.i.BrooklynGarbageCollector [brooklyn-gc]: brooklyn gc (after) - using 328 MB / 496 MB memory (5.58 kB soft); 69 threads; storage: {datagrid={size=7, createCount=7}, refsMapSize=0, listsMapSize=0}; tasks: 10 active, 33 unfinished; 78 remembered, 1696906 total submitted) -{% endhighlight %} +``` These can be extremely useful if investigating a memory or thread leak, or to determine whether a surprisingly high number of tasks are being executed. @@ -201,9 +201,9 @@ One source of high CPU in Brooklyn is when a subscription (e.g. for a policy or triggered many times (i.e. handling many events). A log message like that below will be logged on every 1000 events handled by a given single subscription. -{% highlight text %} +```text 2016-05-30 17:29:09,125 DEBUG o.a.b.c.m.i.LocalSubscriptionManager [brooklyn-execmanager-rvpnFTeL-8]: 1000 events for subscriber Subscription[SCFnav9g;CanopyComposeApp{id=gIeTwhU2}@gIeTwhU2:webapp.url] -{% endhighlight %} +``` If a subscription is handling a huge number of events, there are a couple of common reasons: * first, it could be subscribing to too much activity - e.g. a wildcard subscription for all @@ -216,14 +216,14 @@ If a subscription is handling a huge number of events, there are a couple of com All activity triggered by the REST API or web-console will be logged. Some examples are shown below: -{% highlight text %} +```text 2016-05-19 17:52:30,150 INFO o.a.b.r.r.ApplicationResource [brooklyn-jetty-server-8081-qtp1058726153-17473]: Launched from YAML: name: My Example App location: aws-ec2:us-east-1 services: - type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer 2016-05-30 14:46:19,516 DEBUG brooklyn.REST [brooklyn-jetty-server-8081-qtp1104967201-20881]: Request Tisj14 starting: POST /v1/applications/NiBy0v8Q/entities/NiBy0v8Q/expunge from 77.70.102.66 -{% endhighlight %} +``` #### Entity Activity @@ -235,6 +235,6 @@ include the stdout and stderr of all the commands executed by that entity. It can also be very useful to search for all effector invocations, to see where the behaviour has been triggered: -{% highlight text %} +```text 2016-05-27 12:45:43,529 DEBUG o.a.b.c.m.i.EffectorUtils [brooklyn-execmanager-gvP7MuZF-14364]: Invoking effector stop on TomcatServerImpl{id=mPujYmPd} -{% endhighlight %} +``` http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/upgrade.md ---------------------------------------------------------------------- diff --git a/guide/ops/upgrade.md b/guide/ops/upgrade.md index d24465b..2f87bb9 100644 --- a/guide/ops/upgrade.md +++ b/guide/ops/upgrade.md @@ -281,13 +281,13 @@ Same instructions as above. This section applies only with you are using the RPM/DEB packages. To perform a rollback, please follow these instructions: -{% highlight bash %} +```bash # CentOS / RHEL yum downgrade apache-brooklyn.noarch # Ubuntu Debian dpkg -i apache-brooklyn-xxxx.deb -{% endhighlight %} +``` *Note that to downgrade a DEB package is essentially installing a previous version therefore you need to [download](../misc/download.html) the version you want to downgrade to before hand.* @@ -295,14 +295,14 @@ the version you want to downgrade to before hand.* ## How to stop your service On systemd: -{% highlight bash %} +```bash systemctl stop brooklyn -{% endhighlight %} +``` On upstart: -{% highlight bash %} +```bash stop brooklyn -{% endhighlight %} +``` ## Web login credentials @@ -312,10 +312,10 @@ stop brooklyn * Configure a username/password by modifying [`brooklyn.cfg`](paths.html). An example entry is: -{% highlight bash %} +```bash brooklyn.webconsole.security.users=admin brooklyn.webconsole.security.user.admin.password=password2 -{% endhighlight %} +``` ## Persistence @@ -326,18 +326,18 @@ If you have persisted state you wish to rebind to, persistence is now configured For example, to use S3 for the persisted state, add the following to [`brooklyn.cfg`](paths.html): -{% highlight bash %} +```bash brooklyn.location.named.aws-s3-eu-west-1:aws-s3:eu-west-1 brooklyn.location.named.aws-s3-eu-west-1.identity=<ADD CREDS> brooklyn.location.named.aws-s3-eu-west-1.credential=<ADD CREDS> -{% endhighlight %} +``` To continue the S3 example, for the persisted state, add the following to [`org.apache.brooklyn.osgilauncher.cfg`](paths.html): -{% highlight bash %} +```bash persistenceLocation=aws-s3-eu-west-1 persistenceDir=<ADD HERE> -{% endhighlight %} +``` Apache Brooklyn should be stopped before this file is modified, and then restarted with the new configuration. @@ -347,9 +347,9 @@ in the persisted state. Apache Brooklyn needs to know it in order to read the pe If binding to existing persisted state, an additional command is required to update the existing catalog with the Brooklyn 0.12.0 versions. Assuming Brooklyn has been installed to [`/opt/brooklyn`](paths.html) (as is done by the RPM and DEB): - {% highlight bash %} + ```bash br catalog add /opt/brooklyn/catalog/catalog.bom - {% endhighlight %} + ``` All existing custom jars previously added to lib/plugins (e.g. for Java-based entities) need to be converted to OSGi bundles, and installed in Karaf. The use of the "brooklyn.libraries" section in catalog.bom files will continue to work.
