| |
| |
| |
| |
| <!doctype html> |
| <html lang="en" class="no-js"> |
| <head> |
| |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta http-equiv="x-ua-compatible" content="ie=edge"> |
| |
| |
| |
| |
| <meta name="lang:clipboard.copy" content="Copy to clipboard"> |
| |
| <meta name="lang:clipboard.copied" content="Copied to clipboard"> |
| |
| <meta name="lang:search.language" content="en"> |
| |
| <meta name="lang:search.pipeline.stopwords" content="True"> |
| |
| <meta name="lang:search.pipeline.trimmer" content="True"> |
| |
| <meta name="lang:search.result.none" content="No matching documents"> |
| |
| <meta name="lang:search.result.one" content="1 matching document"> |
| |
| <meta name="lang:search.result.other" content="# matching documents"> |
| |
| <meta name="lang:search.tokenizer" content="[\s\-]+"> |
| |
| <link rel="shortcut icon" href="../../assets/images/favicon.png"> |
| <meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.4.2"> |
| |
| |
| |
| <title>Deployment - Eclipse Hawk</title> |
| |
| |
| |
| <link rel="stylesheet" href="../../assets/stylesheets/application.30686662.css"> |
| |
| <link rel="stylesheet" href="../../assets/stylesheets/application-palette.a8b3c06d.css"> |
| |
| |
| |
| |
| <meta name="theme-color" content="#7e57c2"> |
| |
| |
| |
| <script src="../../assets/javascripts/modernizr.74668098.js"></script> |
| |
| |
| |
| <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono&display=fallback"> |
| <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style> |
| |
| |
| <link rel="stylesheet" href="../../assets/fonts/material-icons.css"> |
| |
| |
| <link rel="stylesheet" href="../../stylesheets/extra.css"> |
| |
| |
| |
| |
| |
| <!-- FAVICON --> |
| <link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png"> |
| <link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png"> |
| <link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png"> |
| <link rel="manifest" href="/img/site.webmanifest"> |
| <link rel="mask-icon" href="/img/safari-pinned-tab.svg" color="#5bbad5"> |
| <link rel="shortcut icon" href="/img/favicon.ico"> |
| <meta name="msapplication-TileColor" content="#b91d47"> |
| <meta name="msapplication-config" content="/img/browserconfig.xml"> |
| <meta name="theme-color" content="#ffffff"> |
| |
| </head> |
| |
| |
| |
| <body dir="ltr" data-md-color-primary="deep-purple" data-md-color-accent="deep-purple"> |
| |
| <svg class="md-svg"> |
| <defs> |
| |
| |
| </defs> |
| </svg> |
| <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> |
| <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> |
| <label class="md-overlay" data-md-component="overlay" for="__drawer"></label> |
| |
| <a href="#initial-setup" tabindex="1" class="md-skip"> |
| Skip to content |
| </a> |
| |
| |
| <header class="md-header" data-md-component="header"> |
| <nav class="md-header-nav md-grid"> |
| <div class="md-flex"> |
| <div class="md-flex__cell md-flex__cell--shrink"> |
| <a href="../.." title="Eclipse Hawk" class="md-header-nav__button md-logo"> |
| |
| <img src="../../assets/images/hawk-logo-white.svg" width="24" height="24"> |
| |
| </a> |
| </div> |
| <div class="md-flex__cell md-flex__cell--shrink"> |
| <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label> |
| </div> |
| <div class="md-flex__cell md-flex__cell--stretch"> |
| <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title"> |
| |
| <span class="md-header-nav__topic"> |
| Eclipse Hawk |
| </span> |
| <span class="md-header-nav__topic"> |
| |
| Deployment |
| |
| </span> |
| |
| </div> |
| </div> |
| <div class="md-flex__cell md-flex__cell--shrink"> |
| |
| <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label> |
| |
| <div class="md-search" data-md-component="search" role="dialog"> |
| <label class="md-search__overlay" for="__search"></label> |
| <div class="md-search__inner" role="search"> |
| <form class="md-search__form" name="search"> |
| <input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active"> |
| <label class="md-icon md-search__icon" for="__search"></label> |
| <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1"> |
|  |
| </button> |
| </form> |
| <div class="md-search__output"> |
| <div class="md-search__scrollwrap" data-md-scrollfix> |
| <div class="md-search-result" data-md-component="result"> |
| <div class="md-search-result__meta"> |
| Type to start searching |
| </div> |
| <ol class="md-search-result__list"></ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| </div> |
| |
| <div class="md-flex__cell md-flex__cell--shrink"> |
| <div class="md-header-nav__source"> |
| |
| |
| |
| |
| |
| <a href="https://git.eclipse.org/c/hawk/hawk.git/" title="Go to repository" class="md-source" data-md-source=""> |
| |
| <div class="md-source__repository"> |
| Git repository @ Eclipse |
| </div> |
| </a> |
| </div> |
| </div> |
| |
| </div> |
| </nav> |
| </header> |
| |
| <div class="md-container"> |
| |
| |
| |
| |
| <main class="md-main" role="main"> |
| <div class="md-main__inner md-grid" data-md-component="container"> |
| |
| |
| <div class="md-sidebar md-sidebar--primary" data-md-component="navigation"> |
| <div class="md-sidebar__scrollwrap"> |
| <div class="md-sidebar__inner"> |
| <nav class="md-nav md-nav--primary" data-md-level="0"> |
| <label class="md-nav__title md-nav__title--site" for="__drawer"> |
| <a href="../.." title="Eclipse Hawk" class="md-nav__button md-logo"> |
| |
| <img src="../../assets/images/hawk-logo-white.svg" width="48" height="48"> |
| |
| </a> |
| Eclipse Hawk |
| </label> |
| |
| <div class="md-nav__source"> |
| |
| |
| |
| |
| |
| <a href="https://git.eclipse.org/c/hawk/hawk.git/" title="Go to repository" class="md-source" data-md-source=""> |
| |
| <div class="md-source__repository"> |
| Git repository @ Eclipse |
| </div> |
| </a> |
| </div> |
| |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../.." title="Home" class="md-nav__link"> |
| Home |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item md-nav__item--nested"> |
| |
| <input class="md-toggle md-nav__toggle" data-md-toggle="nav-2" type="checkbox" id="nav-2"> |
| |
| <label class="md-nav__link" for="nav-2"> |
| Basic use |
| </label> |
| <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> |
| <label class="md-nav__title" for="nav-2"> |
| Basic use |
| </label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../basic-use/installation/" title="Installation" class="md-nav__link"> |
| Installation |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../basic-use/core-concepts/" title="Core concepts" class="md-nav__link"> |
| Core concepts |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../basic-use/examples-xmi/" title="Examples (XMI)" class="md-nav__link"> |
| Examples (XMI) |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../basic-use/examples-modelio/" title="Examples (Modelio)" class="md-nav__link"> |
| Examples (Modelio) |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../basic-use/papyrus/" title="Papyrus UML support" class="md-nav__link"> |
| Papyrus UML support |
| </a> |
| </li> |
| |
| |
| </ul> |
| </nav> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item md-nav__item--nested"> |
| |
| <input class="md-toggle md-nav__toggle" data-md-toggle="nav-3" type="checkbox" id="nav-3"> |
| |
| <label class="md-nav__link" for="nav-3"> |
| Advanced use |
| </label> |
| <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> |
| <label class="md-nav__title" for="nav-3"> |
| Advanced use |
| </label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../advanced-use/graph-as-emf/" title="Graph as EMF model" class="md-nav__link"> |
| Graph as EMF model |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../advanced-use/advanced-props/" title="Advanced properties" class="md-nav__link"> |
| Advanced properties |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../advanced-use/meta-queries/" title="Meta-level queries" class="md-nav__link"> |
| Meta-level queries |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../advanced-use/temporal-queries/" title="Temporal queries" class="md-nav__link"> |
| Temporal queries |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../advanced-use/oomph/" title="Oomph and Hawk" class="md-nav__link"> |
| Oomph and Hawk |
| </a> |
| </li> |
| |
| |
| </ul> |
| </nav> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item md-nav__item--active md-nav__item--nested"> |
| |
| <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4" checked> |
| |
| <label class="md-nav__link" for="nav-4"> |
| Server |
| </label> |
| <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> |
| <label class="md-nav__title" for="nav-4"> |
| Server |
| </label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../architecture/" title="Architecture" class="md-nav__link"> |
| Architecture |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../api/" title="Thrift API" class="md-nav__link"> |
| Thrift API |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../api-security/" title="Thrift API security" class="md-nav__link"> |
| Thrift API security |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item md-nav__item--active"> |
| |
| <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc"> |
| |
| |
| <label class="md-nav__link md-nav__link--active" for="__toc"> |
| Deployment |
| </label> |
| |
| <a href="./" title="Deployment" class="md-nav__link md-nav__link--active"> |
| Deployment |
| </a> |
| |
| |
| <nav class="md-nav md-nav--secondary"> |
| |
| |
| |
| <label class="md-nav__title" for="__toc">Table of contents</label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| <li class="md-nav__item"> |
| <a href="#initial-setup" class="md-nav__link"> |
| Initial setup |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#ini-options" class="md-nav__link"> |
| .ini options |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#ports" class="md-nav__link"> |
| Ports |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#concerns-for-production-environments" class="md-nav__link"> |
| Concerns for production environments |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#secure-storage-of-vcs-credentials" class="md-nav__link"> |
| Secure storage of VCS credentials |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#setting-up-ssl-certificates-for-the-server" class="md-nav__link"> |
| Setting up SSL certificates for the server |
| </a> |
| |
| </li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| </nav> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../cli/" title="Console client" class="md-nav__link"> |
| Console client |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../eclipse/" title="Eclipse client" class="md-nav__link"> |
| Eclipse client |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../file-config/" title="File-based configuration" class="md-nav__link"> |
| File-based configuration |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../logging/" title="Logging" class="md-nav__link"> |
| Logging |
| </a> |
| </li> |
| |
| |
| </ul> |
| </nav> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item md-nav__item--nested"> |
| |
| <input class="md-toggle md-nav__toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5"> |
| |
| <label class="md-nav__link" for="nav-5"> |
| Developers |
| </label> |
| <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> |
| <label class="md-nav__title" for="nav-5"> |
| Developers |
| </label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../developers/run-from-source/" title="Run GUI from source" class="md-nav__link"> |
| Run GUI from source |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../developers/server-from-source/" title="Run Server from source" class="md-nav__link"> |
| Run Server from source |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../developers/plain-maven/" title="Build with plain Maven" class="md-nav__link"> |
| Build with plain Maven |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../developers/website/" title="Work on the website" class="md-nav__link"> |
| Work on the website |
| </a> |
| </li> |
| |
| |
| </ul> |
| </nav> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item md-nav__item--nested"> |
| |
| <input class="md-toggle md-nav__toggle" data-md-toggle="nav-6" type="checkbox" id="nav-6"> |
| |
| <label class="md-nav__link" for="nav-6"> |
| Community |
| </label> |
| <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> |
| <label class="md-nav__title" for="nav-6"> |
| Community |
| </label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="https://www.eclipse.org/forums/index.php/f/442/" title="Forum" class="md-nav__link"> |
| Forum |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="https://gitlab.eclipse.org/eclipse/hawk/hawk/-/issues/new" title="File a bug" class="md-nav__link"> |
| File a bug |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="https://gitlab.eclipse.org/eclipse/hawk/hawk/-/issues" title="Open bugs" class="md-nav__link"> |
| Open bugs |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="https://ci.eclipse.org/hawk/" title="Builds" class="md-nav__link"> |
| Builds |
| </a> |
| </li> |
| |
| |
| </ul> |
| </nav> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="md-nav__item"> |
| <a href="../../additional-resources/" title="Additional resources" class="md-nav__link"> |
| Additional resources |
| </a> |
| </li> |
| |
| |
| </ul> |
| </nav> |
| </div> |
| </div> |
| </div> |
| |
| |
| <div class="md-sidebar md-sidebar--secondary" data-md-component="toc"> |
| <div class="md-sidebar__scrollwrap"> |
| <div class="md-sidebar__inner"> |
| |
| <nav class="md-nav md-nav--secondary"> |
| |
| |
| |
| <label class="md-nav__title" for="__toc">Table of contents</label> |
| <ul class="md-nav__list" data-md-scrollfix> |
| |
| <li class="md-nav__item"> |
| <a href="#initial-setup" class="md-nav__link"> |
| Initial setup |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#ini-options" class="md-nav__link"> |
| .ini options |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#ports" class="md-nav__link"> |
| Ports |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#concerns-for-production-environments" class="md-nav__link"> |
| Concerns for production environments |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#secure-storage-of-vcs-credentials" class="md-nav__link"> |
| Secure storage of VCS credentials |
| </a> |
| |
| </li> |
| |
| <li class="md-nav__item"> |
| <a href="#setting-up-ssl-certificates-for-the-server" class="md-nav__link"> |
| Setting up SSL certificates for the server |
| </a> |
| |
| </li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| </nav> |
| </div> |
| </div> |
| </div> |
| |
| |
| <div class="md-content"> |
| <article class="md-content__inner md-typeset"> |
| |
| |
| |
| <h1>Deployment</h1> |
| |
| <h2 id="initial-setup">Initial setup<a class="headerlink" href="#initial-setup" title="Permanent link">¶</a></h2> |
| <p>To run the Hawk server, download the latest <code>hawk-server-*.zip</code> file for your operating system and architecture of choice from the <a href="https://github.com/mondo-project/mondo-hawk/releases">"Releases" section on Github</a>, and unpack it. Note that <code>-nogpl-</code> releases do not include GPL-licensed components: if you want them in your server, you will have to build it yourself.</p> |
| <p>Make any relevant changes to the <code>mondo-server.ini</code> file, and then run the <code>run-server.sh</code> script from Linux, or simply the provided <code>mondo-server</code> binary from Mac or Windows.</p> |
| <p>If everything goes well, you should see this message:</p> |
| <div class="codehilite"><pre><span></span><code>Welcome to the Hawk Server! |
| List available commands with 'hserverHelp'. |
| Stop the server with 'shutdown' and then 'close'. |
| |
| osgi> |
| </code></pre></div> |
| |
| <p>You may now use the Thrift APIs as normal. If you need to make any tweaks, continue reading!</p> |
| <h2 id="ini-options">.ini options<a class="headerlink" href="#ini-options" title="Permanent link">¶</a></h2> |
| <p>You will notice that the <code>.ini</code> file has quite a few different options defined, in addition to the JVM options defined with <code>-vmargs</code>. We will analyze them in this section.</p> |
| <ul> |
| <li><code>-console</code> allows us to use the OSGi console to manage Hawk instances.</li> |
| <li><code>-consoleLog</code> plugs Eclipse logging into the console, for following what is going with the server.</li> |
| <li><code>-Dartemis.security.enabled=false</code> disables the Shiro security realm for the embedded Artemis server. Production environments should set this to <code>true</code>.</li> |
| <li><code>-Dhawk.artemis.host=localhost</code> has Artemis listening only on 127.0.0.1. You should change this to the IP address or hostname of the network interface that you want Artemis to listen on. Alternatively, you can have Artemis listening in all addresses (see <code>-Dhawk.artemis.listenAll</code> below).</li> |
| <li><code>-Dhawk.artemis.port=61616</code> has Artemis listening on port 61616 in the CORE and STOMP protocols.</li> |
| <li><code>-Dhawk.artemis.listenAll=false</code> prevents Artemis from listening on all addresses. You can set this to <code>true</code> and ignore <code>hawk.artemis.host</code>.</li> |
| <li><code>-Dhawk.artemis.sslEnabled=false</code> disables HTTPS on Artemis. If you enable SSL, you will need to check the "Enabling HTTPS" section further below!</li> |
| <li><code>-Dhawk.tcp.port=2080</code> enables the TCP server for only the Hawk API, and not the Users management one. This API is unsecured, so do this at your own risk. For production environments, you should remove this line.</li> |
| <li><code>-Dhawk.tcp.thriftProtocol=TUPLE</code> changes the Thrift protocol (encoding) that should be used for the TCP endpoint.</li> |
| <li><code>-Dorg.eclipse.equinox.http.jetty.customizer.class=org.hawk.service.server.gzip.Customizer</code> is needed for the * <code>-Dorg.osgi.service.http.port=8080</code> sets the HTTP port for the APIs to 8080.</li> |
| <li><code>-Dorg.osgi.service.http.port.secure=8443</code> sets the HTTPS port for the APIs to 8443.</li> |
| <li><code>-Dosgi.noShutdown=true</code> is needed for the server to stay running.</li> |
| <li><code>-Dsvnkit.library.gnome-keyring.enabled=false</code> is required to work around a bug in the integration of the GNOME keyring in recent Eclipse releases.</li> |
| <li><code>-eclipse.keyring</code> and <code>-eclipse.password</code> are the paths to the keyring and keyring password files which store the VCS credentials Hawk needs to access password-protected SVN repositories. (For Git repositories, you are assumed to keep your own clone and do any periodic pulling yourself.)</li> |
| <li><code>-XX:+UseG1GC</code> (part of <code>-vmargs</code>) improves garbage collection in OrientDB and Neo4j.</li> |
| <li><code>-XX:+UseStringDeduplication</code> (part of <code>-vmargs</code> as well) noticeably reduces memory use in OrientDB.</li> |
| </ul> |
| <h2 id="ports">Ports<a class="headerlink" href="#ports" title="Permanent link">¶</a></h2> |
| <p>These are the default ports that a Hawk server uses:</p> |
| <ul> |
| <li>2080: Hawk raw TCP API, available by default (unsecured: see above for how to disable it)</li> |
| <li>8080: Hawk HTTP API, available by default (optionally secured: see below)</li> |
| <li>8443: Hawk HTTPS API, if enabled (optionally secured: see below)</li> |
| <li>61616: Artemis push notifications for Hawk index status updates (optionally secured / encrypted: see below)</li> |
| </ul> |
| <h2 id="concerns-for-production-environments">Concerns for production environments<a class="headerlink" href="#concerns-for-production-environments" title="Permanent link">¶</a></h2> |
| <p>One important detail for production environments is turning on security. This is disabled by default to help with testing and initial evaluations, but it can be enabled by running the server once, shutting it down and then editing the <code>shiro.ini</code> file appropriately (relevant sections include comments on what to do) and switching <code>artemis.security.enabled</code> to <code>true</code> in the <code>mondo-server.ini</code> file. The MONDO server uses an embedded MapDB database, which is managed through the Users [[Thrift API]]. Once security is enabled, all Thrift APIs and all external (not in-VM) Artemis connections become password-protected.</p> |
| <p>If you enable security, you will want to ensure that <code>-Dhawk.tcp.port</code> is not present in the <code>mondo-server.ini</code> file, since the Hawk TCP port does not support security for the sake of raw performance.</p> |
| <p>If you are deploying this across a network, you will need to edit the <code>mondo-server.ini</code> file and customize the <code>hawk.artemis.host</code> line to the host that you want the Artemis server to listen to. This should be the IP address or hostname of the MONDO server in the network, normally. The Thrift API uses this hostname as well in its replies to the <code>watchModelChanges</code> operation in the Hawk API.</p> |
| <p>Additionally, if the server IP is dynamic but has a consistent DNS name (e.g. an Amazon VM + a dynamic DNS provider), we recommend setting <code>hawk.artemis.listenAll</code> to <code>true</code> (so the Artemis server will keep listening on all interfaces, even if the IP address changes) and using the DNS name for <code>hawk.artemis.host</code> instead of a literal IP address.</p> |
| <p>Finally, production environments should enable and enforce SSL as well, since plain HTTP is insecure. The Linux products include a shell script that generates simple self-signed key/trust stores and indicates which Java system properties should be set on the server and the client.</p> |
| <h2 id="secure-storage-of-vcs-credentials">Secure storage of VCS credentials<a class="headerlink" href="#secure-storage-of-vcs-credentials" title="Permanent link">¶</a></h2> |
| <p>The server hosts a copy of the Hawk model indexer, which may need to access remote Git and Subversion repositories. To access password-protected repositories, the server will need to store the proper credentials in a secure way that will not expose them to other users in the same machine. To achieve this goal, the MONDO server uses the Eclipse secure storage facilities to save the password in an encrypted form. Users need to prepare the secure storage by following these two steps:</p> |
| <ol> |
| <li> |
| <p>The secure store must be placed in a place no other program will try to access concurrently. |
| This can be done by editing the <code>mondo-server.ini</code> server configuration file and adding this: |
| <code>-eclipse.keyring |
| /path/to/keyringfile</code> |
| That path should be only readable by the user running the server, for added security.</p> |
| </li> |
| <li> |
| <p>An encryption password must be set. For Windows and Mac, the available OS integration should |
| be enough. For Linux environments, two lines have to be added at the beginning of the |
| <code>mondo-server.ini</code> file, specifying the path to a password file with: |
| <code>-eclipse.password |
| /path/to/passwordfile.</code> |
| On Linux, creating a password file from 100 bytes of random data that is only readable by |
| the current user can be done with these commands: |
| <code>$ head -c 100 /dev/random | base64 > /path/to/password |
| $ chmod 400 /path/to/password</code></p> |
| </li> |
| </ol> |
| <p>The server tests on startup that the secure store has been set properly, warning users if encryption is not available and urging them to revise their setup.</p> |
| <h2 id="setting-up-ssl-certificates-for-the-server">Setting up SSL certificates for the server<a class="headerlink" href="#setting-up-ssl-certificates-for-the-server" title="Permanent link">¶</a></h2> |
| <p>SSL is handled through standard Java keystore (<code>.jks</code>) files. To produce a keystore with some self-signed certificates, you could use the <code>generate-ssl-certs.sh</code> script included in the Linux distribution, or run these commands from other operating systems (replace CN, OU and so forth with the appropriate values):</p> |
| <div class="codehilite"><pre><span></span><code>keytool -genkey -keystore mondo-server-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=localhost, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA |
| keytool -export -keystore mondo-server-keystore.jks -file mondo-jks.cer -storepass secureexample |
| keytool -import -keystore mondo-client-truststore.jks -file mondo-jks.cer -storepass secureexample -keypass secureexample -noprompt |
| </code></pre></div> |
| |
| <p>Once you have your .jks, on the client .ini you'll need to set:</p> |
| <div class="codehilite"><pre><span></span><code>-Djavax.net.ssl.trustStore=path/to/client-truststore.jks |
| -Djavax.net.ssl.trustStorePassword=secureexample |
| </code></pre></div> |
| |
| <p>On the server .ini, you'll need to enable SSL and tell Jetty and Artemis about your KeyStore:</p> |
| <div class="codehilite"><pre><span></span><code>-Dorg.eclipse.equinox.http.jetty.https.enabled=true |
| -Dhawk.artemis.sslEnabled=true |
| -Dorg.eclipse.equinox.http.jetty.ssl.keystore=path/to/server-keystore.jks |
| -Djavax.net.ssl.keyStore=path/to/server-keystore.jks |
| </code></pre></div> |
| |
| <p>You'll be prompted for the key store password three times: two by Jetty and once by the Artemis server. If you don't want these prompts, you could use these properties, but using them is <em>UNSAFE</em>, as another user in the same machine could retrieve these passwords from your process manager:</p> |
| <div class="codehilite"><pre><span></span><code>-Djavax.net.ssl.keyStorePassword=secureexample |
| -Dorg.eclipse.equinox.http.jetty.ssl.keypassword=secureexample |
| -Dorg.eclipse.equinox.http.jetty.ssl.password=secureexample |
| </code></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </article> |
| </div> |
| </div> |
| </main> |
| |
| |
| <footer class="md-footer"> |
| |
| <div class="md-footer-nav"> |
| <nav class="md-footer-nav__inner md-grid"> |
| |
| <a href="../api-security/" title="Thrift API security" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev"> |
| <div class="md-flex__cell md-flex__cell--shrink"> |
| <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i> |
| </div> |
| <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"> |
| <span class="md-flex__ellipsis"> |
| <span class="md-footer-nav__direction"> |
| Previous |
| </span> |
| Thrift API security |
| </span> |
| </div> |
| </a> |
| |
| |
| <a href="../cli/" title="Console client" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next"> |
| <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"> |
| <span class="md-flex__ellipsis"> |
| <span class="md-footer-nav__direction"> |
| Next |
| </span> |
| Console client |
| </span> |
| </div> |
| <div class="md-flex__cell md-flex__cell--shrink"> |
| <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i> |
| </div> |
| </a> |
| |
| </nav> |
| </div> |
| |
| <div class="md-footer-meta md-typeset"> |
| <div class="md-footer-meta__inner md-grid"> |
| <div class="md-footer-copyright"> |
| |
| <div class="md-footer-copyright__highlight"> |
| Copyright © Eclipse Foundation, Inc. All Rights Reserved. |
| </div> |
| |
| powered by |
| <a href="https://www.mkdocs.org">MkDocs</a> |
| and |
| <a href="https://squidfunk.github.io/mkdocs-material/">Material for MkDocs</a> |
| </div> |
| <div class="md-footer-copyright hawk-eclipse-links"> |
| <ul> |
| <li><a href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li> |
| <li><a href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li> |
| <li><a href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li> |
| </ul> |
| </div> |
| |
| </div> |
| </div> |
| </footer> |
| |
| </div> |
| |
| <script src="../../assets/javascripts/application.c648116f.js"></script> |
| |
| <script>app.initialize({version:"1.0.4",url:{base:"../.."}})</script> |
| |
| |
| </body> |
| </html> |
