Repository: mesos Updated Branches: refs/heads/master e8e9768c7 -> b29ec4f11
http://git-wip-us.apache.org/repos/asf/mesos/blob/b29ec4f1/docs/ssl.md ---------------------------------------------------------------------- diff --git a/docs/ssl.md b/docs/ssl.md new file mode 100644 index 0000000..9df34db --- /dev/null +++ b/docs/ssl.md @@ -0,0 +1,92 @@ +--- +layout: documentation +--- + +# Configuration +There is currently only one implementation of the [libprocess socket interface](https://github.com/apache/mesos/blob/master/3rdparty/libprocess/include/process/socket.hpp) that supports SSL. This implementation uses [libevent](https://github.com/libevent/libevent). Specifically it relies on the `libevent-openssl` library that wraps `openssl`. + +After building Mesos 0.23.0 from source, assuming you have installed the required [Dependencies](#Dependencies), you can modify your configure line to enable SSL as follows: + +~~~ +../configure --enable-libevent --enable-ssl +~~~ + +# Running +Once you have successfully built and installed your new binaries, here are the environment variables that are applicable to the `Master`, `Slave`, `Framework Scheduler/Executor`, or any `libprocess process`: + +#### SSL_ENABLED=(false|0,true|1) [default=false|0] +Turn on or off SSL. When it is turned off it is the equivalent of default mesos with libevent as the backing for events. All sockets default to the non-SSL implementation. When it is turned on, the default configuration for sockets is SSL. This means outgoing connections will use SSL, and incoming connections will be expected to speak SSL as well. None of the below flags are relevant if SSL is not enabled. + +#### SSL_SUPPORT_DOWNGRADE=(false|0,true|1) [default=false|0] +Control whether or not non-SSL connections can be established. If this is enabled __on the accepting side__, then the accepting side will downgrade to a non-SSL socket if the connecting side is attempting to communicate via non-SSL. (e.g. HTTP). See [Upgrading Your Cluster](#Upgrading) for more details. + +#### SSL_CERT_FILE=(path to certificate) +The location of the certificate that will be presented. + +#### SSL_KEY_FILE=(path to key) +The location of the private key used by OpenSSL. + +#### SSL_VERIFY_CERT=(false|0,true|1) [default=false|0] +Control whether certificates are verified when presented. If this is false, even when a certificate is presented, it will not be verified. When `SSL_REQUIRE_CERT` is true, `SSL_VERIFY_CERT` is overridden and all certificates will be verified _and_ required. + +#### SSL_REQUIRE_CERT=(false|0,true|1) [default=false|0] +Enforce that certificates must be presented by connecting clients. This means all connections (including tools hitting endpoints) must present valid certificates in order to establish a connection. + +#### SSL_VERIFY_DEPTH=(N) [default=4] +The maximum depth used to verify certificates. The default is 4. See the OpenSSL documentation or contact your system administrator to learn why you may want to change this. + +#### SSL_CA_DIR=(path to CA directory) +The directory used to find the certificate authority / authorities. You can specify `SSL_CA_DIR` or `SSL_CA_FILE` depending on how you want to restrict your certificate authorization. + +#### SSL_CA_FILE=(path to CA file) +The file used to find the certificate authority. You can specify `SSL_CA_DIR` or `SSL_CA_FILE` depending on how you want to restrict your certificate authorization. + +#### SSL_CIPHERS=(accepted ciphers separated by ':') [default=AES128-SHA:AES256-SHA:RC4-SHA:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA] +A list of `:`-separated ciphers. Use these if you want to restrict or open up the accepted ciphers for OpenSSL. Read the OpenSSL documentation or contact your system administrators to see whether you want to override the default values. + +#### SSL_ENABLE_SSL_V3=(false|0,true|1) [default=false|0] +#### SSL_ENABLE_TLS_V1_0=(false|0,true|1) [default=false|0] +#### SSL_ENABLE_TLS_V1_1=(false|0,true|1) [default=false|0] +#### SSL_ENABLE_TLS_V1_2=(false|0,true|1) [default=true|1] +The above switches enable / disable the specified protocols. By default only TLS V1.2 is enabled. SSL V2 is always disabled; there is no switch to enable it. The mentality here is to restrict security by default, and force users to open it up explicitly. Many older version of the protocols have known vulnerabilities, so only enable these if you fully understand the risks. +_SSLv2 is disabled completely because modern versions of OpenSSL disable it using multiple compile time configuration options._ +#<a name="Dependencies"></a>Dependencies + +### libevent +We require the OpenSSL support from libevent. The suggested version of libevent is [`2.0.22-stable`](https://github.com/libevent/libevent/releases/tag/release-2.0.22-stable). As new releases come out we will try to maintain compatibility. + +~~~ +// For example, on OSX: +brew install libevent +~~~ + +### OpenSSL +We require [OpenSSL](https://github.com/openssl/openssl). There are multiple branches of OpenSSL that are being maintained by the community. Since security requires being vigilant, we recommend reading the release notes for the current releases of OpenSSL and deciding on a version within your organization based on your security needs. Mesos is not too deeply dependent on specific OpenSSL versions, so there is room for you to make security decisions as an organization. +Please ensure the `event2` and `openssl` headers are available for building mesos. + +~~~ +// For example, on OSX: +brew install openssl +~~~ + +# <a name="Upgrading"></a>Upgrading Your Cluster +_There is no SSL specific requirement for upgrading different components in a specific order._ + +The recommended strategy is to restart all your components to enable SSL with downgrades support enabled. Once all components have SSL enabled, then do a second restart of all your components to disable downgrades. This strategy will allow each component to be restarted independently at your own convenience with no time restrictions. It will also allow you to try SSL in a subset of your cluster. __NOTE:__ While different components in your cluster are serving SSL vs non-SSL traffic, any relative links in the WebUI may be broken. Please see the [WebUI](#WebUI) section for details. Here are sample commands for upgrading your cluster: + +~~~ +// Restart each component with downgrade support (master, slave, framework): +SSL_ENABLED=true SSL_SUPPORT_DOWNGRADE=true SSL_KEY_FILE=<path-to-your-private-key> SSL_CERT_FILE=<path-to-your-certificate> <Any other SSL_* environment variables you may choose> <your-component (e.g. bin/master.sh)> <your-flags> + +// Restart each component WITHOUT downgrade support (master, slave, framework): +SSL_ENABLED=true SSL_SUPPORT_DOWNGRADE=false SSL_KEY_FILE=<path-to-your-private-key> SSL_CERT_FILE=<path-to-your-certificate> <Any other SSL_* environment variables you may choose> <your-component (e.g. bin/master.sh)> <your-flags> +~~~ +The end state is a cluster that is only communicating with SSL. + +__NOTE:__ Any tools you may use that communicate with your components must be able to speak SSL, or they will be denied. You may choose to maintain `SSL_SUPPORT_DOWNGRADE=true` for some time as you upgrade your internal tooling. The advantage of `SSL_SUPPORT_DOWNGRADE=true` is that all components that speak SSL will do so, while other components may still communicate over insecure channels. + +# <a name="WebUI"></a>WebUI +The default Mesos WebUI uses relative links. Some of these links transition between endpoints served by the master and slaves. The WebUI currently does not have enough information to change the 'http' vs 'https' links based on whether the target endpoint is currently being served by an SSL-enabled binary. This may cause certain links in the WebUI to be broken when a cluster is in a transition state between SSL and non-SSL. Any tools that hit these endpoints will still be able to access them as long as they hit the endpoint using the right protocol, or the `SSL_SUPPORT_DOWNGRADE` option is set to true. + +### Certificates +Most browsers have built in protection that guard transitions between pages served using different certificates. For this reason you may choose to serve both the master and slave endpoints using a common certificate that covers multiple hostnames. If you do not do this, certain links, such as those to slave sandboxes, may seem broken as the browser treats the transition between differing certificates transition as unsafe. http://git-wip-us.apache.org/repos/asf/mesos/blob/b29ec4f1/docs/submitting-a-patch.md ---------------------------------------------------------------------- diff --git a/docs/submitting-a-patch.md b/docs/submitting-a-patch.md index 78ffcfb..cbd99fe 100644 --- a/docs/submitting-a-patch.md +++ b/docs/submitting-a-patch.md @@ -30,10 +30,10 @@ layout: documentation ### Create your patch 1. Create one or more test cases to exercise the bug or the feature (the Mesos team uses [test-driven development](http://en.wikipedia.org/wiki/Test-driven_development)). Before you start coding, make sure these test cases all fail. - 1. The [testing patterns](mesos-testing-patterns.md) page has some suggestions for writing test cases. + 1. The [testing patterns](testing-patterns.md) page has some suggestions for writing test cases. 2. Make your changes to the code (using whatever IDE/editor you choose) to actually fix the bug or implement the feature. - 1. Before beginning, please read the [Mesos C++ Style Guide](mesos-c++-style-guide.md). It is recommended to use the git pre-commit hook (`support/hooks/pre-commit`) to automatically check for style errors. See the hook script for instructions to enable it. + 1. Before beginning, please read the [Mesos C++ Style Guide](c++-style-guide.md). It is recommended to use the git pre-commit hook (`support/hooks/pre-commit`) to automatically check for style errors. See the hook script for instructions to enable it. 2. Most of your changes will probably be to files inside of `BASE_MESOS_DIR` 3. From inside of the root Mesos directory: `./bootstrap` (Only required if building from git repository). 4. To build, we recommend that you don't build inside of the src directory. We recommend you do the following: @@ -77,4 +77,4 @@ layout: documentation 4. The last step is to ensure that the necessary documentation gets created or updated so the whole world knows about your new feature or bug fix. ## Style Guides -* For patches to the core, we ask that you follow the [Mesos C++ Style Guide](mesos-c++-style-guide.md). +* For patches to the core, we ask that you follow the [Mesos C++ Style Guide](c++-style-guide.md). http://git-wip-us.apache.org/repos/asf/mesos/blob/b29ec4f1/docs/testing-patterns.md ---------------------------------------------------------------------- diff --git a/docs/testing-patterns.md b/docs/testing-patterns.md new file mode 100644 index 0000000..d0d92ff --- /dev/null +++ b/docs/testing-patterns.md @@ -0,0 +1,81 @@ +--- +layout: documentation +--- + +# Mesos Testing Patterns + +A collection of common testing patterns used in Mesos tests. If you have found a good way to test a certain condition that you think may be useful for other cases, please document it here together with motivation and background. + +## Using `Clock` magic to ensure an event is processed +Scheduling a sequence of events in an asynchronous environment is not easy: a function call usually initiates an action and returns immediately, while the action runs in background. A simple, obvious, and bad solution is to use `os::sleep()` to wait for action completion. The time the action needs to finish may vary on different machines, while increasing sleep duration increases the test execution time and slows down `make check`. One of the right ways to do it is to wait for an action to finish and proceed right after. This is possible using libprocess' `Clock` routines. + + +Every message enqueued in a libprocess process' (or actor's, to avoid ambiguity with OS processes) mailbox is processed by `ProcessManager` (right now there is a single instance of `ProcessManager` per OS process, but this may change in the future). `ProcessManager` fetches actors from the runnable actors list and services all events from the actor's mailbox. Using `Clock::settle()` call we can block the calling thread until `ProcessManager` empties mailboxes of all actors. Here is the example of this pattern: + +~~~{.cpp} +// As Master::killTask isn't doing anything, we shouldn't get a status update. +EXPECT_CALL(sched, statusUpdate(&driver, _)) + .Times(0); + +// Set expectation that Master receives killTask message. +Future<KillTaskMessage> killTaskMessage = + FUTURE_PROTOBUF(KillTaskMessage(), _, master.get()); + +// Attempt to kill unknown task while slave is transitioning. +TaskID unknownTaskId; +unknownTaskId.set_value("2"); + +// Stop the clock. +Clock::pause(); + +// Initiate an action. +driver.killTask(unknownTaskId); + +// Make sure the event associated with the action has been queued. +AWAIT_READY(killTaskMessage); + +// Wait for all messages to be dispatched and processed completely to satisfy +// the expectation that we didn't receive a status update. +Clock::settle(); + +Clock::resume(); +~~~ + +## Intercepting a message sent to a different OS process +Intercepting messages sent between libprocess processes (let's call them actors to avoid ambiguity with OS processes) that live in the same OS process is easy, e.g.: + +~~~{.cpp} +Future<SlaveReregisteredMessage> slaveReregisteredMessage = + FUTURE_PROTOBUF(SlaveReregisteredMessage(), _, _); +... +AWAIT_READY(slaveReregisteredMessage); +~~~ + +However, this won't work if we want to intercept a message sent to an actor (technically a `UPID`) that lives in another OS process. For example, `CommandExecutor` spawned by a slave will live in a separate OS process, though master and slave instances live in the same OS process together with our test (see `mesos/src/tests/cluster.hpp`). The wait in this code will fail: + +~~~{.cpp} +Future<ExecutorRegisteredMessage> executorRegisteredMessage = + FUTURE_PROTOBUF(ExecutorRegisteredMessage(), _, _); +... +AWAIT_READY(executorRegisteredMessage); +~~~ + +### Why messages sent outside the OS process are not intercepted? +Libprocess events may be filtered (see `libprocess/include/process/filter.hpp`). `FUTURE_PROTOBUF` uses this ability and sets an expectation on a `filter` method of `TestsFilter` class with a `MessageMatcher`, that matches the message we want to intercept. The actual filtering happens in `ProcessManager::resume()`, which fetches messages from the queue of the received events. + +*No* filtering happens when sending, encoding, or transporting the message (see e.g. `ProcessManager::deliver()` or `SocketManager::send()`). Therefore in the aforementioned example, `ExecutorRegisteredMessage` leaves the slave undetected by the filter, reaches another OS process where executor lives, gets enqueued into the `CommandExecutorProcess`' mailbox and can be filtered there, but remember our expectation is set in another OS process! + +### How to workaround +Consider setting expectations on corresponding incoming messages ensuring they are processed and therefore ACK message is sent. + +For the aforementioned example, instead of intercepting `ExecutorRegisteredMessage`, we can intercept `RegisterExecutorMessage` and wait until its processed, which includes sending `ExecutorRegisteredMessage` (see `Slave::registerExecutor()`): + +~~~{.cpp} +Future<RegisterExecutorMessage> registerExecutorMessage = + FUTURE_PROTOBUF(RegisterExecutorMessage(), _, _); +... +AWAIT_READY(registerExecutorMessage); +Clock::pause(); +Clock::settle(); +Clock::resume(); +~~~ http://git-wip-us.apache.org/repos/asf/mesos/blob/b29ec4f1/docs/tools.md ---------------------------------------------------------------------- diff --git a/docs/tools.md b/docs/tools.md index 414decf..3e5f4d7 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -20,10 +20,10 @@ These tools make it easy to set up and run a Mesos cluster. If you want to hack on Mesos or write a new framework, these tools will help. -* [clang-format](/documentation/latest/clang-format/) to automatically apply some of the style rules dictated by the [Mesos C++ Style Guide](/documentation/latest/mesos-c++-style-guide/). +* [clang-format](/documentation/latest/clang-format/) to automatically apply some of the style rules dictated by the [Mesos C++ Style Guide](/documentation/latest/c++-style-guide/). * [Go Bindings and Examples](https://github.com/mesosphere/mesos-go) Write a Mesos framework in Go! Comes with an example scheduler and executor. * [Mesos Framework giter8 Template](https://github.com/mesosphere/scala-sbt-mesos-framework.g8) This is a giter8 template. The result of applying this template is a bare-bones Apache Mesos framework in Scala using SBT for builds and Vagrant for testing on a singleton cluster. * [Scala Hello World](https://gist.github.com/guenter/7471695) A simple Mesos "Hello World": downloads and starts a web server on every node in the cluster. * [Xcode Workspace](https://github.com/tillt/xcode-mesos) Hack on Mesos in Xcode. -Can't find yours in the list? Please submit a patch, or email [email protected] and we'll add you! \ No newline at end of file +Can't find yours in the list? Please submit a patch, or email [email protected] and we'll add you!
