This is an automated email from the ASF dual-hosted git repository. duncangrant pushed a commit to branch ruby-3 in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
commit 93fa774142de7a47db69d0e3e0e80b56cd49bf09 Merge: 1e0f1be edc13bd Author: Richard Downer <[email protected]> AuthorDate: Thu Feb 25 14:20:29 2021 +0000 Merge apache-brooklyn/master as at commit edc13bd6 guide/blueprints/advanced-example.md | 2 +- guide/blueprints/creating-yaml.md | 2 +- guide/blueprints/custom-entities.md | 8 +- guide/blueprints/effectors.md | 4 +- guide/blueprints/entity-configuration.md | 4 +- guide/blueprints/java/defining-and-deploying.md | 4 +- guide/blueprints/java/entities.md | 4 +- guide/blueprints/java/feeds.md | 6 +- guide/blueprints/policies.md | 2 +- guide/blueprints/test/usage-examples.md | 4 +- guide/blueprints/winrm/client.md | 26 ++-- guide/blueprints/winrm/index.md | 82 +++++----- guide/blueprints/yaml-reference.md | 2 +- guide/dev/code/structure.md | 2 +- guide/locations/_azure-ARM.md | 4 +- guide/locations/_azure-classic.md | 4 +- guide/locations/_byon.md | 2 +- guide/locations/_clouds.md | 2 +- guide/locations/_cloudstack.md | 4 +- guide/locations/index.md | 172 +++++++++++++++++++++ .../locations/provisioned-machine-requirements.md | 2 +- guide/ops/cli/cli-ref-guide.md | 2 +- guide/ops/configuration/brooklyn_cfg.md | 2 +- guide/ops/high-availability/index.md | 2 +- guide/ops/persistence/index.md | 2 +- guide/ops/production-installation.md | 2 +- guide/ops/requirements.md | 8 +- guide/ops/security-guidelines.md | 4 +- guide/ops/server-cli-reference.md | 4 +- guide/ops/troubleshooting/_connectivity.md | 152 ------------------ guide/ops/troubleshooting/connectivity.md | 150 +++++++++++++++++- guide/ops/troubleshooting/deployment.md | 2 +- guide/ops/troubleshooting/overview.md | 2 +- guide/ops/troubleshooting/slow-unresponsive.md | 2 +- 34 files changed, 422 insertions(+), 254 deletions(-) diff --cc guide/blueprints/creating-yaml.md index 3122d42,fe3d5a7..a866330 --- a/guide/blueprints/creating-yaml.md +++ b/guide/blueprints/creating-yaml.md @@@ -37,8 -31,8 +37,8 @@@ open a new browser window (usually) at Click on the tile "Blueprint Composer", then on the double-arrow located on the top right of the screen (to switch to the YAML mode), paste the copied YAML into the editor and press "Deploy". There are several other ways to deploy, including `curl` and via the command-line, - and you can configure users, https, persistence, and more, + and you can configure users, HTTPS, persistence, and more, -as described [in the ops guide]({{book.path.docs}}/ops/index.md). +as described [in the ops guide]({{ site.path.guide }}/ops/). [](web-console-yaml.png) diff --cc guide/blueprints/custom-entities.md index 1bbe059,1d3cb6a..6f86335 --- a/guide/blueprints/custom-entities.md +++ b/guide/blueprints/custom-entities.md @@@ -285,10 -261,10 +285,10 @@@ command over ssh every 5 seconds. This is to disable the ssh-polling (by setting `sshMonitoring.enabled: false`) and to configure a different health-check. -See documentation on the [Entity's error status]({{book.path.docs}}/ops/troubleshooting/overview.md#entitys-error-status) +See documentation on the [Entity's error status]({{ site.path.guide }}/ops/troubleshooting/overview.html#entitys-error-status) for how Brooklyn models an entity's health. - In the snippet below, we'll define a new health-check sensor (via http polling), and will automatically add this + In the snippet below, we'll define a new health-check sensor (via HTTP polling), and will automatically add this to the `service.notUp.indicators`. If that map is non-empty, then the entity's `service.isUp` will be set automatically to `false`: diff --cc guide/blueprints/java/defining-and-deploying.md index 11a2889,1290d03..b657102 --- a/guide/blueprints/java/defining-and-deploying.md +++ b/guide/blueprints/java/defining-and-deploying.md @@@ -173,5 -161,5 +173,5 @@@ The YAML blueprint below shows an examp Note the type name matches the id defined in the `.bom` file. -You can now call the effector by any of the standard means - [web console]({{book.path.docs}}/ops/gui/index.md), -[REST API]({{book.path.docs}}/ops/rest.md), or [Client CLI]({{book.path.docs}}/ops/cli/index.md). +You can now call the effector by any of the standard means - [web console]({{ site.path.guide }}/ops/gui/), - [REST api]({{ site.path.guide }}/ops/rest.html), or [Client CLI]({{ site.path.guide }}/ops/cli/). ++[REST API]({{ site.path.guide }}/ops/rest.html), or [Client CLI]({{ site.path.guide }}/ops/cli/). diff --cc guide/blueprints/java/entities.md index 1e2623d,eea5aa1..38a24e6 --- a/guide/blueprints/java/entities.md +++ b/guide/blueprints/java/entities.md @@@ -95,10 -94,10 +95,10 @@@ protected void disconnectSensors() super.disconnectSensors(); if (httpFeed != null) httpFeed.stop(); } -``` +{% endhighlight %} - In this example (a simplified version of ``JBoss7Server``), the url returns metrics in JSON. - We report the entity as up if we get back an http response code of 200, or down if any other response code or exception. + In this example (a simplified version of ``JBoss7Server``), the URL returns metrics in JSON. + We report the entity as up if we get back an HTTP response code of 200, or down if any other response code or exception. We retrieve the request count from the response body, and convert it to an integer. Note the first line (``super.connectSensors()``); as one descends into specific convenience subclasses (such as for Java web-apps), the work done by the parent class's overridden methods may be relevant, and will want to be invoked or even added to a resulting list. diff --cc guide/blueprints/java/feeds.md index 4c151de,52c1edc..748e5c0 --- a/guide/blueprints/java/feeds.md +++ b/guide/blueprints/java/feeds.md @@@ -35,9 -34,9 +35,9 @@@ important that the entity's `rebind()` ##### HTTP Feed - An `HttpFeed` polls over http(s). An example is shown below: + An `HttpFeed` polls over HTTP(S). An example is shown below: -```java +{% highlight java %} private HttpFeed feed; @Override @@@ -95,9 -94,9 +95,9 @@@ protected void disconnectSensors() ##### WinRm CMD Feed - A WinRM feed executes a windows command over winrm periodically. An example is shown below: + A WinRM feed executes a Windows command over WinRM periodically. An example is shown below: -```java +{% highlight java %} private AbstractCommandFeed feed; //@Override diff --cc guide/blueprints/test/usage-examples.md index 54b1826,63bb1bb..5d1883e --- a/guide/blueprints/test/usage-examples.md +++ b/guide/blueprints/test/usage-examples.md @@@ -33,12 -25,10 +33,12 @@@ This `TestEffector` example demonstrate - `TestCase` entity starts its children sequentially - asserts that the `webappcluster` entity `service.isUp` sensor is `true` within 10 minutes of the parent `TestCase` entity starting. Blocks start of the next child until it obtains a result (or times out). - - `deploy` effector invoked to deploy war to a `newcontext` with a 5 minute timeout to allow completion of the deploy task. - - asserts `/newcontext` url returns a HTTP status code 200 within 5 minutes of the effector being invoked (Note that this timeout is relative to the preceding test entity as they are being sequentially run as children of a `TestCase` entity). + - `deploy` effector invoked to deploy WAR to a `newcontext` with a 5 minute timeout to allow completion of the deploy task. + - asserts `/newcontext` URL returns a HTTP status code 200 within 5 minutes of the effector being invoked (Note that this timeout is relative to the preceding test entity as they are being sequentially run as children of a `TestCase` entity). -!CODEFILE "example_yaml/testcases/effector-test-snippet.yaml" +{% highlight yaml %} +{% readj example_yaml/testcases/effector-test-snippet.yaml %} +{% endhighlight %} ### HTTP Call Tests Demonstrates the following HTTP Call assertions against the specified `url`, which in these examples are being built from the `webappcluster` entities `host.address` and `proxy.http.port` sensors (the tester having flexibility in how the test URL is to be constructed): diff --cc guide/blueprints/winrm/index.md index ce1f6af,5451bf1..9bdc5aa --- a/guide/blueprints/winrm/index.md +++ b/guide/blueprints/winrm/index.md @@@ -72,10 -69,10 +72,10 @@@ A Sample Blueprin Creating a Windows VM is done using the `org.apache.brooklyn.entity.software.base.VanillaWindowsProcess` entity type. This is very similar to `VanillaSoftwareProcess`, but adapted to work for Windows and WinRM instead of Linux. We suggest you read the -[documentation for VanillaSoftwareProcess]({{book.path.docs}}/blueprints/custom-entities.md#vanilla-software-using-bash) to find out what you +[documentation for VanillaSoftwareProcess]({{ site.path.guide }}/blueprints/custom-entities.html#vanilla-software-using-bash) to find out what you can do with this entity. - Entity authors are strongly encouraged to write Windows Powershell or Batch scripts as separate + Entity authors are strongly encouraged to write Windows PowerShell or Batch scripts as separate files, to configure these to be uploaded, and then to configure the appropriate command as a single line that executes given script. @@@ -120,10 -117,10 +120,10 @@@ The installation script - referred to a Where security-related operation are to be executed, it may require the use of `CredSSP` to obtain the correct Administrator privileges: you may otherwise get an access denied error. See the sub-section - [How and Why to re-authenticate within a powershell script](#how-and-why-to-re-authenticate-within-a-powershell-script) for more details. + [How and Why to re-authenticate within a PowerShell script](#how-and-why-to-re-authenticate-within-a-powershell-script) for more details. This is only a very simple example. A more complex example can be found in the [Microsoft SQL Server blueprint in the -Brooklyn source code]({{book.url.brooklyn_library_git}}/{{"master" if 'SNAPSHOT' in book.brooklyn_version else book.brooklyn_version}}/software/database/src/main/resources/org/apache/brooklyn/entity/database/mssql). +Brooklyn source code]({{ site.brooklyn.url.git }}/software/database/src/main/resources/org/apache/brooklyn/entity/database/mssql). Tips and Tricks diff --cc guide/locations/_azure-ARM.md index 84d5df1,9134c96..c213ae0 --- a/guide/locations/_azure-ARM.md +++ b/guide/locations/_azure-ARM.md @@@ -215,9 -209,9 +215,9 @@@ stored in protected .PFX file. It need * `additionalUnattendContent` Additional content. Normally it can be defined as `null` - * `enableAutomaticUpdates` whether to enable the automatic windows updates. It can be set to `false`, if automatic updates are not desired + * `enableAutomaticUpdates` whether to enable the automatic Windows updates. It can be set to `false`, if automatic updates are not desired -##### Sample Windows Blueprint +###### Sample Windows Blueprint Placeholders surrounded with `<>` have to be replcaced with their respective values. diff --cc guide/locations/_azure-classic.md index 18604a2,b853998..c19bfb4 --- a/guide/locations/_azure-classic.md +++ b/guide/locations/_azure-classic.md @@@ -187,9 -181,9 +187,9 @@@ services Below is an example named location for Azure, configured in `brooklyn.properties`. Note the placeholder values for the identity, credential and password. -```properties +{% highlight properties %} brooklyn.location.named.myazure=jclouds:azurecompute:West Europe - brooklyn.location.named.myazure.displayName=Azure West Europe (windows) + brooklyn.location.named.myazure.displayName=Azure West Europe (Windows) brooklyn.location.named.myazure.identity=$HOME/.brooklyn/azure.p12 brooklyn.location.named.myazure.credential=<P12_EXPORT_PASSWORD> brooklyn.location.named.myazure.endpoint=https://management.core.windows.net/<YOUR_SUBSCRIPTION_ID> @@@ -220,10 -214,10 +220,10 @@@ This approach differs from the behaviou by the cloud provider and is then retrieved via the cloud provider's API after provisioning the VM. -##### WinRM Configuration +###### WinRM Configuration The WinRM initialization in Azure is achieved through configuration options in the VM provisioning request. - The required configuration is to enabled HTTPS (if Azure is told to use http, the VM comes pre-configured + The required configuration is to enabled HTTPS (if Azure is told to use HTTP, the VM comes pre-configured with WinRM encrypted over HTTP). The default is then to support NTLM protocol. The setup of Windows VMs on Azure differs from that on other clouds, such as AWS. In contrast, on AWS an diff --cc guide/locations/_byon.md index 948994d,6ff66e8..3c59be5 --- a/guide/locations/_byon.md +++ b/guide/locations/_byon.md @@@ -52,10 -46,10 +52,10 @@@ This location will be saved as a [catal For more complex host configuration, one can define custom config values per machine. In the example below, there will be two machines. The first will be a machine reachable on - `ssh -i ~/.ssh/brooklyn.pem -p 8022 [email protected]`. The second is a windows machine, reachable + `ssh -i ~/.ssh/brooklyn.pem -p 8022 [email protected]`. The second is a Windows machine, reachable over WinRM. Each machine has also has a private address (e.g. for within a private network). -```yaml +{% highlight yaml %} location: byon: hosts: diff --cc guide/locations/index.md index 9092ada,e7f199f..066ab03 --- a/guide/locations/index.md +++ b/guide/locations/index.md @@@ -12,10 -8,180 +12,182 @@@ to a pre-provisioned network or to loca See also: -* The [Locations yaml guide]({{book.path.docs}}/blueprints/setting-locations.md) +* The [Locations yaml guide]({{ site.path.guide }}/blueprints/setting-locations.html) * Use within an entity of the configuration option - [provisioning.properties]({{book.path.docs}}/blueprints/entity-configuration.md#entity-provisioningproperties-overriding-and-merging) -* How to add location definitions to the [Catalog]({{book.path.docs}}/blueprints/catalog/index.md); and -* How to use [Externalized Configuration]({{book.path.docs}}/ops/externalized-configuration.md). + [provisioning.properties]({{ site.path.guide }}/blueprints/entity-configuration.html#entity-provisioningproperties-overriding-and-merging) +* How to add location definitions to the [Catalog]({{ site.path.guide }}/blueprints/catalog/); and +* How to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html). + The requirements for how a provisioned machine should behave will depend on the + entites subsequently deployed there. + + Below are a set of common assumptions, made by many entity implementations, which + could cause subsequent errors if they do not hold. These relate to the machine's + configuration, rather than additional networking or security that a given Cloud + might offer. + + Also see the [Troubleshooting]({{book.path.docs}}/ops/troubleshooting/index.md) docs. + +{% child_content %} ++ + + ## Remote Access + + ### SSH or WinRM Access + + Many entities require ssh'ing (or using WinRM for Windows), to install and configure + the software. + + An example of disabling all ssh'ing is shown below: + + location: + aws-ec2:us-east-1: + identity: XXXXXXXX + credential: XXXXXXXX + waitForSshable: false + pollForFirstReachableAddress: false + services: + - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess + brooklyn.config: + onbox.base.dir.skipResolution: true + sshMonitoring.enabled: false + + + ### Parsing SSH stdout: No Extra Lines + + For entities that execute ssh commands, these sometimes parse the resulting stdout. + + It is strongly recommended that VMs are configured so that no additional stdout is written when executing + remote ssh (or WinRM) commands. Such stdout risks interfering with the response parsing in some blueprints. + + For example, if configuring the VM to write out "Last login" information, this should be done for only + "interactive" shells (see [Stackoverflow](http://stackoverflow.com/a/415444/1393883) for more details). + + + ### Passwordless Sudo + + Does passwordless sudo work? + + Try executing: + + sudo whoami + + See [Passwordless Sudo](#passwordless-sudo). + + + ## Advertised Addresses + + ### Hostname Resolves Locally + + Does the hostname known at the box resolve at the box? + + Try executing: + + ping $(hostname) + + if not, consider setting `generate.hostname: true` in the location config, for jclouds-based locations. + + + ### IP Resolves Locally + + For the IP address advertised in Brooklyn using the sensor `host.addresses.private` (or `host.subnet.address`), + can the machine reach that IP? + + Get the sensor value, and then try executing: + + ping ${PRIVATE_IP} + + Is there a public IP (advertised using the sensor `host.addresses.public`, or `host.address`), and can the + machine reach it? + + Get the sensor value, and then try executing: + + ping ${PUBLIC_IP} + + + ## Networking + + ### Public Internet Access + + Can the machine reach the public internet, and does DNS resolve? + + Try executing: + + ping www.example.org + + + ### Machine's Hostname in DNS + + Is the machine hostname well-known? If ones does a DNS lookup, e.g. from the Brooklyn server, does it resolve and + does it return the expected IP (e.g. the same IP as the `host.addresses.public` sensor)? Try using the hostname + that the machine reports when you execute `hostname`. + + Many blueprints do not require this, instead using IP addresses directly. Some blueprints may include registration + with an appropriate DNS server. Some clouds do this automatically. + + + ### Reachability + + When provisioning two machines, can these two machines reach each other on the expected IP(s) and hostname(s)? + + Try using `ping` from one machine to another using the public or subnet ip or hostname. + However, note that `ping` requires access over ICMP, which may be disabled. Alternatively, + try connecting to a specific TCP port using `telnet <address> <port>`. + + + ### Firewalls + + What firewall(s) are running on the machine, and are the required ports open? + On Linux, check things like `iptables`, `firewalld`, `ufw` or other commercial + firewalls. On Windows, check the settings of the + [Windows Firewall](https://en.wikipedia.org/wiki/Windows_Firewall). + + Consider using `openIptables: true`, or even `stopIptables: true`. + + + ## Sufficient Entropy for /dev/random + + Is there sufficient entropy on the machine, for `/dev/random` to respond quickly? + + Try executing: + + { cat /dev/random > /tmp/x & } ; sleep 10 ; kill %1 ; { cat /dev/random > /tmp/x & } ; sleep 1 ; kill %1 ; wc /tmp/x | awk '{print $3}' + + The result should be more than 1M. + + If not, consider setting `installDevUrandom: true` for jclouds-based locations. + + See instructions to [Increase Entropy]({{book.path.docs}}/ops/troubleshooting/increase-entropy.md). + + + ## File System + + ### Permissions of /tmp + + Is `/tmp` writable? + + Try executing: + + touch /tmp/amp-test-file ; rm /tmp/amp-test-file + + Are files in `/tmp` executable (e.g. some places it has been mounted NO_EXECUTE)? + + Try executing: + + echo date > /tmp/brooklyn-test.sh && chmod +x /tmp/brooklyn-test.sh && /tmp/brooklyn-test.sh && rm /tmp/brooklyn-test.sh + + {% include '_clouds.md' %} + {% include '_AWS.md' %} + {% include '_azure-ARM.md' %} + {% include '_azure-classic.md' %} + {% include '_cloudstack.md' %} + {% include '_GCE.md' %} + {% include '_ibm-softlayer.md' %} + {% include '_openstack.md' %} + {% include '_inheritance-and-named-locations.md' %} + {% include '_byon.md' %} + {% include '_ssh-keys.md' %} + {% include '_localhost.md' %} + {% include '_location-customizers.md' %} + {% include '_location-customizer-security-groups.md' %} + {% include '_special-locations.md' %} diff --cc guide/ops/production-installation.md index 7825bdc,77a6abe..7fdb9bb --- a/guide/ops/production-installation.md +++ b/guide/ops/production-installation.md @@@ -28,12 -25,12 +28,12 @@@ 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]({{book.path.docs}}/locations/index.md#ssh-keys), if not available -* if the "localhost" location will be used, enable [passwordless ssh login]({{book.path.docs}}/locations/index.md#ssh-keys) +* 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) * 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 [Linux kernel entropy]({{book.path.docs}}/ops/troubleshooting/increase-entropy.md) is sufficient -* check that the [ulimit values]({{book.path.docs}}/ops/troubleshooting/increase-system-resource-limits.md) are sufficiently high ++* 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 * 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/). diff --cc guide/ops/requirements.md index aa63853,43968df..d5378ab --- a/guide/ops/requirements.md +++ b/guide/ops/requirements.md @@@ -109,7 -108,7 +109,7 @@@ It is normally recommended that Brookly ### 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.docs}}/ops/troubleshooting/increase-entropy.md) is sufficient. ++Check that the [Linux kernel entropy]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) is sufficient. ### System Resource Limits diff --cc guide/ops/server-cli-reference.md index f30fa06,6e29b25..2f689b1 --- a/guide/ops/server-cli-reference.md +++ b/guide/ops/server-cli-reference.md @@@ -51,13 -50,13 +51,13 @@@ The Server CLI arguments for [persisten ### Path Setup - 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: + 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: -```bash +{% highlight bash %} BROOKLYN_HOME=/path/to/brooklyn/ export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/ -``` +{% endhighlight %} ### Memory Usage diff --cc guide/ops/troubleshooting/connectivity.md index 3faeacf,d49ad67..98ea2bb --- a/guide/ops/troubleshooting/connectivity.md +++ b/guide/ops/troubleshooting/connectivity.md @@@ -1,8 -1,154 +1,156 @@@ --- +layout: website-normal title: Troubleshooting Server Connectivity Issues in the Cloud +toc: /guide/toc.json --- - {% readj _connectivity.md %} + A common problem when setting up an application in the cloud is getting the basic connectivity right - how + do I get my service (e.g. a TCP host:port) publicly accessible over the internet? + + This varies a lot - e.g. Is the VM public or in a private network? Is the service only accessible through + a load balancer? Should the service be globally reachable or only to a particular CIDR? + + This guide gives some general tips for debugging connectivity issues, which are applicable to a + range of different service types. Choose those that are appropriate for your use-case. + + ## VM reachable + If the VM is supposed to be accessible directly (e.g. from the public internet, or if in a private network + then from a jump host)... + + ### ping + Can you `ping` the VM from the machine you are trying to reach it from? + + However, ping is over ICMP. If the VM is unreachable, it could be that the firewall forbids ICMP but still + lets TCP traffic through. + + ### telnet to TCP port + You can check if a given TCP port is reachable and listening using `telnet <host> <port>`, such as + `telnet www.google.com 80`, which gives output like: + + ~~~ + Trying 31.55.163.219... + Connected to www.google.com. + Escape character is '^]'. + ~~~ + + If this is very slow to respond, it can be caused by a firewall blocking access. If it is fast, it could + be that the server is just not listening on that port. + + ### DNS and routing + If using a hostname rather than IP, then is it resolving to a sensible IP? + + Is the route to the server sensible? (e.g. one can hit problems with proxy servers in a corporate + network, or ISPs returning a default result for unknown hosts). + + The following commands can be useful: + + * `host` is a DNS lookup utility. e.g. `host www.google.com`. + * `dig` stands for "domain information groper". e.g. `dig www.google.com`. + * `traceroute` prints the route that packets take to a network host. e.g. `traceroute www.google.com`. + + ## Proxy settings + Depending on the type of location, brooklyn might use HTTP to provision machines (clocker, jclouds). If the host environment defines proxy settings, these might interfere with the reachability of the respective HTTP service. + + One such case is using VirtualBox with host-only or private internal network settings, while using an external proxy for accessing the internet. It is clear that the external proxy won't be able to route HTTP calls properly, but that might not be clear when reading the logs (although brooklyn will present the failing URL). + + Try accessing the web-service URLs from a browser via the proxy, or perhaps try running brooklyn with proxy disabled: + + ~~~ + export http_proxy= + bin/brooklyn launch + ~~~ + + If a system-level proxy server has been configured, you can instruct brooklyn to use the proxy server by passing `-Djava.net.useSystemProxies=true` to the JVM + + ## Service is listening + + ### Service responds + Try connecting to the service from the VM itself. For example, `curl http://localhost:8080` for a + web-service. + + On dev/test VMs, don't be afraid to install the utilities you need such as `curl`, `telnet`, `nc`, + etc. Cloud VMs often have a very cut-down set of packages installed. For example, execute + `sudo apt-get update; sudo apt-get install -y curl` or `sudo yum install -y curl`. + + ### Listening on port + Check that the service is listening on the port, and on the correct NIC(s). + + Execute `netstat -antp` (or on OS X `netstat -antp TCP`) to list the TCP ports in use (or use + `-anup` for UDP). You should expect to see the something like the output below for a service. + + ~~~ + Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name + tcp 0 0 :::8080 :::* LISTEN 8276/java + ~~~ + + In this case a Java process with pid 8276 is listening on port 8080. The local address `:::8080` + format means all NICs (in IPv6 address format). You may also see `0.0.0.0:8080` for IPv4 format. + If it says 127.0.0.1:8080 then your service will most likely not be reachable externally. + + Use `ip addr show` (or the obsolete `ifconfig -a`) to see the network interfaces on your server. + + For `netstat`, run with `sudo` to see the pid for all listed ports. + + ## Firewalls + On Linux, check if `iptables` is preventing the remote connection. On Windows, check the Windows Firewall. + + If it is acceptable (e.g. it is not a server in production), try turning off the firewall temporarily, + and testing connectivity again. Remember to re-enable it afterwards! On CentOS, this is `sudo service + iptables stop`. On Ubuntu, use `sudo ufw disable`. On Windows, press the Windows key and type 'Windows + Firewall with Advanced Security' to open the firewall tools, then click 'Windows Firewall Properties' + and set the firewall state to 'Off' in the Domain, Public and Private profiles. + + If you cannot temporarily turn off the firewall, then look carefully at the firewall settings. For + example, execute `sudo iptables -n --list` and `iptables -t nat -n --list`. + + ## Cloud firewalls + Some clouds offer a firewall service, where ports need to be explicitly listed to be reachable. + + For example, + [security groups for AWS EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html) + have rules for the protocols and ports to be reachable from specific CIDRs. + + Check these settings via the cloud provider's web-console (or API). + + ## Quick test of a listener port + It can be useful to start listening on a given port, and to then check if that port is reachable. + This is useful for testing basic connectivity when your service is not yet running, or to a + different port to compare behaviour, or to compare with another VM in the network. + + The `nc` netcat tool is useful for this. For example, `nc -l 0.0.0.0 8080` will listen on port + TCP 8080 on all network interfaces. On another server, you can then run `echo hello from client + | nc <hostname> 8080`. If all works well, this will send "hello from client" over the TCP port 8080, + which will be written out by the `nc -l` process before exiting. + + Similarly for UDP, you use `-lU`. + + You may first have to install `nc`, e.g. with `sudo yum install -y nc` or `sudo apt-get install netcat`. + + ### Cloud load balancers + For some use-cases, it is good practice to use the load balancer service offered by the cloud provider + (e.g. [ELB in AWS](http://aws.amazon.com/elasticloadbalancing/) or the [Cloudstack Load Balancer] + (http://docs.cloudstack.apache.org/projects/cloudstack-installation/en/latest/network_setup.html#management-server-load-balancing)) + + The VMs can all be isolated within a private network, with access only through the load balancer service. + + Debugging techniques here include ensuring connectivity from another jump server within the private + network, and careful checking of the load-balancer configuration from the Cloud Provider's web-console. + + ### DNAT + Use of DNAT is appropriate for some use-cases, where a particular port on a particular VM is to be + made available. + + Debugging connectivity issues here is similar to the steps for a cloud load balancer. Ensure + connectivity from another jump server within the private network. Carefully check the NAT rules from + the Cloud Provider's web-console. + + ### Guest wifi + It is common for guest wifi to restrict access to only specific ports (e.g. 80 and 443, restricting + ssh over port 22 etc). + + Normally your best bet is then to abandon the guest wifi (e.g. to tether to a mobile phone instead). + + There are some unconventional workarounds such as [configuring sshd to listen on port 80 so you can + use an ssh tunnel](http://askubuntu.com/questions/107173/is-it-possible-to-ssh-through-port-80). + However, the firewall may well inspect traffic so sending non-HTTP traffic over port 80 may still fail. diff --cc guide/ops/troubleshooting/slow-unresponsive.md index 6551759,888549d..fbae62f --- a/guide/ops/troubleshooting/slow-unresponsive.md +++ b/guide/ops/troubleshooting/slow-unresponsive.md @@@ -105,7 -103,7 +105,7 @@@ netstat -an | grep ESTABLISHED | wc - 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.docs}}/ops/troubleshooting/increase-entropy.md) ++[Linux kernel entropy]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) for details of how to work around this.
