355 lines
20 KiB
HTML
355 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" dir="ltr">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<title>documentation:2.0:upgrade</title>
|
|
<meta name="generator" content="DokuWiki"/>
|
|
<meta name="robots" content="index,follow"/>
|
|
<meta name="keywords" content="documentation,2.0,upgrade"/>
|
|
<link rel="search" type="application/opensearchdescription+xml" href="lib/exe/opensearch.html" title="LemonLDAP::NG"/>
|
|
<link rel="start" href="upgrade.html"/>
|
|
<link rel="contents" href="upgrade.html" title="Sitemap"/>
|
|
<link rel="stylesheet" type="text/css" href="lib/exe/css.php.t.bootstrap3.css"/>
|
|
<!-- //if:usedebianlibs
|
|
<link rel="stylesheet" type="text/css" href="/javascript/bootstrap/css/bootstrap.min.css" />
|
|
//elsif:useexternallibs
|
|
<link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css"></script>
|
|
//elsif:cssminified
|
|
<link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.min.css" />
|
|
//else -->
|
|
<link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.css" />
|
|
<!-- //endif -->
|
|
<script type="text/javascript">/*<![CDATA[*/var NS='documentation:2.0';var JSINFO = {"id":"documentation:2.0:upgrade","namespace":"documentation:2.0"};
|
|
/*!]]>*/</script>
|
|
<script type="text/javascript" charset="utf-8" src="lib/exe/js.php.t.bootstrap3.js"></script>
|
|
<!-- //if:usedebianlibs
|
|
<script type="text/javascript" src="/javascript/jquery/jquery.min.js"></script>
|
|
//elsif:useexternallibs
|
|
<script type="text/javascript" src="http://code.jquery.com/jquery-2.2.0.min.js"></script>
|
|
//elsif:jsminified
|
|
<script type="text/javascript" src="/static/bwr/jquery/dist/jquery.min.js"></script>
|
|
//else -->
|
|
<script type="text/javascript" src="/static/bwr/jquery/dist/jquery.js"></script>
|
|
<!-- //endif -->
|
|
<!-- //if:usedebianlibs
|
|
<script type="text/javascript" src="/javascript/jquery-ui/jquery-ui.min.js"></script>
|
|
//elsif:useexternallibs
|
|
<script type="text/javascript" src="http://code.jquery.com/ui/1.10.4/jquery-ui.min.js"></script>
|
|
//elsif:jsminified
|
|
<script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.min.js"></script>
|
|
//else -->
|
|
<script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.js"></script>
|
|
<!-- //endif -->
|
|
</head>
|
|
<body>
|
|
<div class="dokuwiki export container">
|
|
<!-- TOC START -->
|
|
<div id="dw__toc">
|
|
<h3 class="toggle">Table of Contents</h3>
|
|
<div>
|
|
|
|
<ul class="toc">
|
|
<li class="level1"><div class="li"><a href="#upgrade_order_from_19">Upgrade order from 1.9.*</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#installation">Installation</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#configuration">Configuration</a></div>
|
|
<ul class="toc">
|
|
<li class="level2"><div class="li"><a href="#configuration_refresh">Configuration refresh</a></div></li>
|
|
</ul>
|
|
</li>
|
|
<li class="level1"><div class="li"><a href="#ldap_connection">LDAP connection</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#kerberos_or_ssl_usage">Kerberos or SSL usage</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#logs">Logs</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#security">Security</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#handlers">Handlers</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#rules_and_headers">Rules and headers</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#supported_servers">Supported servers</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#ajax_requests">Ajax requests</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#soaprest_services">SOAP/REST services</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#cas">CAS</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#developer_corner">Developer corner</a></div>
|
|
<ul class="toc">
|
|
<li class="level2"><div class="li"><a href="#apis">APIs</a></div></li>
|
|
<li class="level2"><div class="li"><a href="#portal_overview">Portal overview</a></div></li>
|
|
<li class="level2"><div class="li"><a href="#handler">Handler</a></div></li>
|
|
</ul></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<!-- TOC END -->
|
|
<div class="notetip"><strong>Upgrade from 2.0.x to 2.0.x</strong> : nothing to do !
|
|
</div>
|
|
<h1 class="sectionedit1" id="upgrade_from_19_to_20">Upgrade from 1.9 to 2.0</h1>
|
|
<div class="level1">
|
|
<div class="noteimportant">2.0 is a major release, lot of things have been changed. You must read this document before upgrade.
|
|
</div>
|
|
</div>
|
|
<!-- EDIT1 SECTION "Upgrade from 1.9 to 2.0" [69-232] -->
|
|
<h2 class="sectionedit2" id="upgrade_order_from_19">Upgrade order from 1.9.*</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
As usual, if you use more than 1 server and don't want to stop <abbr title="Single Sign On">SSO</abbr> service AND IF YOU HAVE NO INCOMPATIBILITY MENTIONED IN THIS DOCUMENT, upgrade must be done in the following order:
|
|
</p>
|
|
<ol>
|
|
<li class="level1"><div class="li"> servers with handlers only;</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> portal servers <em>(all together if your load balancer is stateless (user or client <abbr title="Internet Protocol">IP</abbr>) and if users use the menu)</em>;</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> manager server</div>
|
|
</li>
|
|
</ol>
|
|
<div class="noteimportant">You must revalidate your configuration using the manager.
|
|
</div>
|
|
</div>
|
|
<!-- EDIT2 SECTION "Upgrade order from 1.9.*" [233-707] -->
|
|
<h2 class="sectionedit3" id="installation">Installation</h2>
|
|
<div class="level2">
|
|
<div class="noteimportant">French documentation is no more available. Only English version of this documentation is maintained now.
|
|
</div>
|
|
<p>
|
|
This release of <abbr title="LemonLDAP::NG">LL::NG</abbr> requires these minimal versions of GNU/Linux distributions:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Debian 9 (stretch)</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> Ubuntu 16.04 LTS</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> CentOS 7</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> RHEL 7</div>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
For <abbr title="Security Assertion Markup Language">SAML</abbr> features, we require at least Lasso 2.5 and we recommend Lasso 2.6.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT3 SECTION "Installation" [708-1093] -->
|
|
<h2 class="sectionedit4" id="configuration">Configuration</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> <strong>lemonldap-ng.ini</strong> requires some new fields in portal section. Update yours using the one given installed by default. New requires fields are:</div>
|
|
<ul>
|
|
<li class="level2"><div class="li"> <strong>staticPrefix</strong> <em>(manager and portal)</em>: the path to static content</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> <strong>templateDir</strong> <em>(manager and portal)</em>: the path to templates directory</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> <strong>languages</strong> <em>(manager and portal)</em>: accepted languages</div>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="level1"><div class="li"> Portal skins are now in <code>/usr/share/lemonldap-ng/portal/templates</code>. See <a href="portalcustom.html#skin_customization" class="wikilink1" title="documentation:2.0:portalcustom">skin customization</a> to adapt your templates.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> User module in authentication parameters now provides a “Same as authentication” value. You must revalidate it in the manager since all special values must be replaced by this <em>(Multi, Choice, Proxy, Slave, <abbr title="Security Assertion Markup Language">SAML</abbr>, OpenID*,...)</em></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> <strong>“Multi” doesn't exist anymore</strong>: it is replaced by <a href="authcombination.html" class="wikilink1" title="documentation:2.0:authcombination">Combination</a>, a more powerful module.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> Apache and Nginx configurations must be updated to use FastCGI portal</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> URLs for mail reset and register pages have changed, you must update configuration parameters. For example:</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code :perl"> mailUrl <span class="sy0">=></span> <span class="st_h">'http://auth.example.com/resetpwd'</span><span class="sy0">,</span>
|
|
registerUrl <span class="sy0">=></span> <span class="st_h">'http://auth.example.com/register'</span><span class="sy0">,</span></pre>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Option <code>trustedProxies</code> was removed, you must now configure your Web Server to manage <code>X-Forwarded-For</code> header, see <a href="behindproxyminihowto.html" class="wikilink1" title="documentation:2.0:behindproxyminihowto">how to run LL::NG behind a reverse proxy</a>.</div>
|
|
</li>
|
|
</ul>
|
|
<div class="noteimportant">Apache mod_perl has got lot of troubleshooting problems since 2.4 version <em>(many segfaults,...)</em>, especially when using MPM worker or MPM event. That's why <abbr title="LemonLDAP::NG">LL::NG</abbr> doesn't use anymore ModPerl::Registry: all is now handled by FastCGI <em>(portal and manager)</em>, except for Apache2 Handler.
|
|
<p>
|
|
<strong>For Handlers, it is now recommended to migrate to Nginx</strong>, but Apache 2.4 is still supported with MPM prefork.
|
|
</p>
|
|
|
|
</div>
|
|
</div>
|
|
<!-- EDIT4 SECTION "Configuration" [1094-2921] -->
|
|
<h3 class="sectionedit5" id="configuration_refresh">Configuration refresh</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
Now portal has the same behavior than handlers: it looks to configuration stored in local cache every 10 minutes. So it has to be reload like every handler.
|
|
</p>
|
|
<div class="noteimportant">If you want to use reload mechanism on a portal only host, you must install a handler in Portal host to be able to refresh local cache. Include <code>handler-nginx.conf</code> or <code>handler-apache2.conf</code> for example
|
|
</div>
|
|
</div>
|
|
<!-- EDIT5 SECTION "Configuration refresh" [2922-3343] -->
|
|
<h2 class="sectionedit6" id="ldap_connection">LDAP connection</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
Now LDAP connections are kept open to improve performances. To allow that, <abbr title="LemonLDAP::NG">LL::NG</abbr> requires an anonymous access to LDAP RootDSE entry to check connection.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT6 SECTION "LDAP connection" [3344-3527] -->
|
|
<h2 class="sectionedit7" id="kerberos_or_ssl_usage">Kerberos or SSL usage</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> A new <a href="authkerberos.html" class="wikilink1" title="documentation:2.0:authkerberos">Kerberos</a> authentication backend has been added since 2.0. This module solves many Kerberos integration problems <em>(usage in conjunction with other backends, better error display,…)</em>. However, you can retain the old integration manner <em>(using <a href="authapache.html" class="wikilink1" title="documentation:2.0:authapache">Apache authentication module</a>)</em>.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> For <a href="authssl.html" class="wikilink1" title="documentation:2.0:authssl">SSL</a>, a new <a href="authssl.html#ssl_by_ajax" class="wikilink1" title="documentation:2.0:authssl">Ajax option</a> can be used in the same idea: so SSL can be used in conjunction with other backends.</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT7 SECTION "Kerberos or SSL usage" [3528-4036] -->
|
|
<h2 class="sectionedit8" id="logs">Logs</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> <strong>Syslog</strong>: logs are now configured in <code>lemonldap-ng.ini</code> file only. If you use Syslog, you must reconfigure it. See <a href="logs.html" class="wikilink1" title="documentation:2.0:logs">logs</a> for more.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> <strong>Apache2</strong>: Portal doesn't use anymore Apache2 logger. Logs are always written to Apache error.log but Apache “LogLevel” parameter has no more effect on it. Portal is now a FastCGI application and doesn't use anymore ModPerl. See <a href="logs.html" class="wikilink1" title="documentation:2.0:logs">logs</a> for more.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> If you are running behind a proxy, make sure LemonLDAP::NG can <a href="behindproxyminihowto.html" class="wikilink1" title="documentation:2.0:behindproxyminihowto">see the original IP address</a> of incoming HTTP connections</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT8 SECTION "Logs" [4037-4618] -->
|
|
<h2 class="sectionedit9" id="security">Security</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
LLNG portal now embeds the following features:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> <a href="https://en.wikipedia.org/wiki/Cross-site_request_forgery" class="urlextern" title="https://en.wikipedia.org/wiki/Cross-site_request_forgery" rel="nofollow">CSRF</a> protection <em>(Cross-Site Request Forgery)</em>: a token is build for each form. To disable it, set requireToken to 0 <em>(portal security parameters in the manager)</em></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> <a href="https://en.wikipedia.org/wiki/Content_Security_Policy" class="urlextern" title="https://en.wikipedia.org/wiki/Content_Security_Policy" rel="nofollow">Content-Security-Policy</a> header: portal build dynamically this header. You can modify default values in the manager <em>(Général parameters » Advanced parameters » Security » Content-Security-Policy)</em></div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT9 SECTION "Security" [4619-5186] -->
|
|
<h2 class="sectionedit10" id="handlers">Handlers</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> <strong>Apache only</strong>:</div>
|
|
<ul>
|
|
<li class="level2"><div class="li"> <strong>Apache handler</strong> is now Lemonldap::NG::Handler::ApacheMP2 and Menu is now Lemonldap::NG::Handler::ApacheMP2::Menu</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> because of an Apache behaviour change, PerlHeaderParserHandler must no more be used with “reload” URLs <em>(replaced by PerlResponseHandler)</em>. Any “reload url” that are inside a protected vhost must be unprotected in vhost rules <em>(protection has to be done by web server configuration)</em>.</div>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="level1"><div class="li"> <a href="cda.html" class="wikilink1" title="documentation:2.0:cda">CDA</a>, <a href="documentation/latest/applications/zimbra.html" class="wikilink1" title="documentation:latest:applications:zimbra">ZimbraPreAuth</a>, <a href="securetoken.html" class="wikilink1" title="documentation:2.0:securetoken">SecureToken</a> and <a href="handlerauthbasic.html" class="wikilink1" title="documentation:2.0:handlerauthbasic">AuthBasic</a> are now <a href="handlerarch.html" class="wikilink1" title="documentation:2.0:handlerarch">Handler Types</a>. So there is no more special file to load: you just have to choose “VirtualHost type” in the manager/VirtualHosts.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> <a href="ssocookie.html" class="wikilink1" title="documentation:2.0:ssocookie">SSOCookie</a>: Since Firefox 60 and Chrome 68, “+2d, +5M, 12h and so on...” cookie expiration time notation is no more supported. CookieExpiration value is a number of seconds until the cookie expires. A zero or negative number will expire the cookie immediately.</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT10 SECTION "Handlers" [5187-6272] -->
|
|
<h2 class="sectionedit11" id="rules_and_headers">Rules and headers</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> hostname() and remote_ip() are no more provided to avoid some name conflicts <em>(replaced by $ENV{})</em></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> <code>$ENV{<cgi_variable>}</code> is now available everywhere: see <a href="writingrulesand_headers.html" class="wikilink1" title="documentation:2.0:writingrulesand_headers">Writing rules and headers</a></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> some variable names have changed. See <a href="variables.html" class="wikilink1" title="documentation:2.0:variables">variables</a> document</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT11 SECTION "Rules and headers" [6273-6591] -->
|
|
<h2 class="sectionedit12" id="supported_servers">Supported servers</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> Apache-1.3 files are not provided now. You can build them yourself by looking at Apache-2 configuration files</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT12 SECTION "Supported servers" [6592-6737] -->
|
|
<h2 class="sectionedit13" id="ajax_requests">Ajax requests</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
Before 2.0, an Ajax query launched after session timeout received a 302 code. Now a 401 HTTP code is returned. <code>WWW-Authenticate</code> header contains: <code><abbr title="Single Sign On">SSO</abbr> <portal-<abbr title="Uniform Resource Locator">URL</abbr>></code>
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT13 SECTION "Ajax requests" [6738-6935] -->
|
|
<h2 class="sectionedit14" id="soaprest_services">SOAP/REST services</h2>
|
|
<div class="level2">
|
|
<ul>
|
|
<li class="level1"><div class="li"> SOAP server activation is now split in 2 parameters (configuration/sessions). You must set them else SOAP service will be disabled</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> Notifications are now REST/JSON by default. You can force old format in the manager. Note that SOAP proxy has changed: <a href="http://portal/notifications" class="urlextern" title="http://portal/notifications" rel="nofollow">http://portal/notifications</a> now.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> If you use “adminSessions” endpoint with “singleSession*” features, you must upgrade all portals simultaneously</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> SOAP services can be replaced by new REST services</div>
|
|
</li>
|
|
</ul>
|
|
<div class="noteimportant"><a href="handlerauthbasic.html" class="wikilink1" title="documentation:2.0:handlerauthbasic">AuthBasic Handler</a> uses now REST services instead of SOAP.
|
|
</div>
|
|
</div>
|
|
<!-- EDIT14 SECTION "SOAP/REST services" [6936-7533] -->
|
|
<h2 class="sectionedit15" id="cas">CAS</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
<abbr title="Central Authentication Service">CAS</abbr> authentication module no more use perl <abbr title="Central Authentication Service">CAS</abbr> client, but our own code. You can now define several <abbr title="Central Authentication Service">CAS</abbr> servers in a specific branch in Manager, like you can define several <abbr title="Security Assertion Markup Language">SAML</abbr> or OpenID Connect providers.
|
|
</p>
|
|
|
|
<p>
|
|
<abbr title="Central Authentication Service">CAS</abbr> issuer module has also been improved, you must modify the configuration of <abbr title="Central Authentication Service">CAS</abbr> clients to move them from virtual host branch to <abbr title="Central Authentication Service">CAS</abbr> client branch.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT15 SECTION "CAS" [7534-7911] -->
|
|
<h2 class="sectionedit16" id="developer_corner">Developer corner</h2>
|
|
<div class="level2">
|
|
|
|
</div>
|
|
<!-- EDIT16 SECTION "Developer corner" [7912-7941] -->
|
|
<h3 class="sectionedit17" id="apis">APIs</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
Portal has now many REST features and includes an <abbr title="Application Programming Interface">API</abbr> plugin. See Portal manpages to learn how to write auth modules, issuers or other features.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT17 SECTION "APIs" [7942-8103] -->
|
|
<h3 class="sectionedit18" id="portal_overview">Portal overview</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
Portal is no more a single CGI object. Since 2.0, It is based on Plack/PSGI and Mouse modules. Little resume
|
|
</p>
|
|
<pre class="file">Portal object
|
|
|
|
|
+-> auth module
|
|
|
|
|
+-> userDB module
|
|
|
|
|
+-> issuer modules
|
|
|
|
|
+-> other plugins (notification,...)</pre>
|
|
|
|
<p>
|
|
Requests are independent objects based on Lemonldap::NG::Portal::Main::Request which inherits from Lemonldap::NG::Common::PSGI::Request which inherits from Plack::Request. See manpages for more.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT18 SECTION "Portal overview" [8104-8579] -->
|
|
<h3 class="sectionedit19" id="handler">Handler</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
Handler libraries have been totally rewritten. If you've made custom handlers, they must be rewritten, see <a href="customhandlers.html" class="wikilink1" title="documentation:2.0:customhandlers">customhandlers</a>.
|
|
</p>
|
|
|
|
<p>
|
|
If you used self protected CGI, you also need to rewrite them, see <a href="selfmadeapplication.html#perl_auto-protected_cgi" class="wikilink1" title="documentation:2.0:selfmadeapplication">documentation</a>.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT19 SECTION "Handler" [8580-] --></div>
|
|
</body>
|
|
</html>
|