diff --git a/docs/index.adoc b/docs/index.adoc index 8350338..40ba8d0 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -27,6 +27,7 @@ include::quota-reload.adoc[leveloffset=+1] include::video.adoc[leveloffset=+1] include::logs.adoc[leveloffset=+1] include::download.adoc[leveloffset=+1] +include::tls.adoc[leveloffset=+1] include::how-it-works.adoc[leveloffset=+1] include::multiple-instances.adoc[leveloffset=+1] include::log-files.adoc[leveloffset=+1] diff --git a/docs/quota-files.adoc b/docs/quota-files.adoc index bc14bc6..5ad1c57 100644 --- a/docs/quota-files.adoc +++ b/docs/quota-files.adoc @@ -4,7 +4,9 @@ . For user ```username``` quota file should be named ```username.xml```. . Each quota file contains the following XML: + -```xml +.A typical quota file +[source,xml] +---- @@ -26,7 +28,7 @@ ... -``` +---- + Here we define a list of browser names, their versions and default version for each browser. Each version has one or more regions (in cloud term, i.e. data centers). Every region contains one or more hosts. Each host defined in XML should have Selenium listening on specified port. The XML namespace is needed to be fully compatible with http://github.com/seleniumkit/gridrouter[original] Java GridRouter implementation. + @@ -37,6 +39,7 @@ NOTE: A frequent question being asked is the meaning of `count` attribute becaus . Similarly version `platform` attribute is matched against `platform` or `platformName` capability by prefix. When platform from capabilities equals to `ANY` - default platform will be chosen. . Sometimes you may need to have the same browser name and version on different platforms, e.g. Firefox on both Linux and Windows. To achieve this you need to add `defaultPlatform` and `platform` attributes to quota file as follows: + +.Adding platform information to quota file [source,xml] ---- @@ -90,6 +93,8 @@ Having this URL Ggr will append session ID and proxy VNC traffic from: === Working with External Selenium Services Although Ggr is mainly used for creating your own Selenium cluster you can also configure it to obtain some browsers in external Selenium services such as http://saucelabs.com/[Saucelabs], http://browserstack.com/[BrowserStack] or https://testingbot.com/[TestingBot]. These services always require username and password to be specified. Credentials should be set for each browser version in respective quota file: + +.Providing user name and password for external Selenium service [source,xml] ---- diff --git a/docs/tls.adoc b/docs/tls.adoc new file mode 100644 index 0000000..dbac693 --- /dev/null +++ b/docs/tls.adoc @@ -0,0 +1,68 @@ +== Encrypting Connection to Ggr + +Ggr itself does not support any modern encryption technologies such as https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS] or https://en.wikipedia.org/wiki/WebSocket[WebSocket Secure]. In order to use them you are expected to setup a reverse proxy having such capabilities. A typical http://nginx.org/[Nginx] configuration looks like the following: + +.Nginx configuration for encrypted connection +---- +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +upstream ggr { + server ggr1.example.com:4444 weight=10 max_fails=30 fail_timeout=180s; + server ggr2.example.com:4444 weight=10 max_fails=30 fail_timeout=180s; + server ggr3.example.com:4444 weight=10 max_fails=30 fail_timeout=180s; +} + +server { + server_name selenium.example.com; + + listen 4444 ssl; + listen [::]:4444 ssl; + + ssl_prefer_server_ciphers on; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers kEECDH+AESGCM+AES128:kEECDH+AES128:kRSA+AESGCM+AES128:kRSA+AES128:DES-CBC3-SHA:!RC4:!aNULL:!eNULL:!MD5:!EXPORT:!LOW:!SEED:!CAMELLIA:!IDEA:!PSK:!SRP:!SSLv2; + ssl_session_cache shared:SSL:64m; + ssl_session_timeout 28h; + + # These two files are private key and certificate from SSL certificate provider + ssl_certificate /etc/ssl/selenium.pem; + ssl_certificate_key /etc/ssl/selenium.key; + + access_log /var/log/nginx/selenium_access.log; + error_log /var/log/nginx/selenium_error.log; + + location / { + proxy_pass http://ggr; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_connect_timeout 10; + proxy_send_timeout 300; + proxy_read_timeout 300; + proxy_buffers 32 64m; + proxy_buffer_size 64k; + proxy_next_upstream error timeout http_502 http_503 http_504; + client_max_body_size 64m; + client_body_buffer_size 64m; + add_header Access-Control-Allow-Methods "GET,PUT,OPTIONS,POST,DELETE"; + add_header Access-Control-Allow-Origin "*"; + add_header Access-Control-Allow-Headers "Content-Type,Authorization"; + add_header Access-Control-Allow-Credentials "true"; + } + + location ~ ^/vnc/ { + proxy_pass http://ggr; + proxy_http_version 1.1; + proxy_read_timeout 950s; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + +} +---- +