lemonldap-ng/doc/pages/documentation/current/configlocation.html

<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
  <meta charset="utf-8" />
  <title>documentation:2.0:configlocation</title>
<meta name="generator" content="DokuWiki"/>
<meta name="robots" content="index,follow"/>
<meta name="keywords" content="documentation,2.0,configlocation"/>
<link rel="search" type="application/opensearchdescription+xml" href="lib/exe/opensearch.html" title="LemonLDAP::NG"/>
<link rel="start" href="configlocation.html"/>
<link rel="contents" href="configlocation.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:configlocation","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="#backends">Backends</a></div></li>
<li class="level1"><div class="li"><a href="#manager">Manager</a></div></li>
<li class="level1"><div class="li"><a href="#configuration_text_editor">Configuration text editor</a></div></li>
<li class="level1"><div class="li"><a href="#command_line_interface_cli">Command Line Interface (CLI)</a></div></li>
<li class="level1"><div class="li"><a href="#apache">Apache</a></div>
<ul class="toc">
<li class="level2"><div class="li"><a href="#portal">Portal</a></div></li>
<li class="level2"><div class="li"><a href="#manager1">Manager</a></div></li>
<li class="level2"><div class="li"><a href="#handler">Handler</a></div></li>
</ul>
</li>
<li class="level1"><div class="li"><a href="#nginx">Nginx</a></div>
<ul class="toc">
<li class="level2"><div class="li"><a href="#portal1">Portal</a></div></li>
<li class="level2"><div class="li"><a href="#manager2">Manager</a></div></li>
<li class="level2"><div class="li"><a href="#handler1">Handler</a></div></li>
</ul>
</li>
<li class="level1"><div class="li"><a href="#configuration_reload">Configuration reload</a></div></li>
<li class="level1"><div class="li"><a href="#local_file">Local file</a></div></li>
</ul>
</div>
</div>
<!-- TOC END -->

<h1 class="sectionedit1" id="configuration_overview">Configuration overview</h1>
<div class="level1">

</div>
<!-- EDIT1 SECTION "Configuration overview" [1-38] -->
<h2 class="sectionedit2" id="backends">Backends</h2>
<div class="level2">

<p>
LemonLDAP::NG configuration is stored in a backend that allows all modules to access it.
</p>
<div class="noteimportant">Note that all <abbr title="LemonLDAP::NG">LL::NG</abbr> components must have access:<ul>
<li class="level1"><div class="li"> to the configuration backend</div>
</li>
<li class="level1"><div class="li"> to the sessions storage backend</div>
</li>
</ul>

<p>
Detailed configuration backends documentation is available <a href="start.html#configuration_database" class="wikilink1" title="documentation:2.0:start">here</a>.
</p>

</div>
<p>
By default, configuration is stored in <a href="fileconfbackend.html" class="wikilink1" title="documentation:2.0:fileconfbackend">files</a>, so access trough network is not possible. To allow this, use <a href="soapconfbackend.html" class="wikilink1" title="documentation:2.0:soapconfbackend">SOAP</a> for configuration access, or use a network service like <a href="sqlconfbackend.html" class="wikilink1" title="documentation:2.0:sqlconfbackend">SQL database</a> or <a href="ldapconfbackend.html" class="wikilink1" title="documentation:2.0:ldapconfbackend">LDAP directory</a>.
</p>

<p>
Configuration backend can be set in the <a href="#local_file" title="documentation:2.0:configlocation ↵" class="wikilink1">local configuration file</a>, in <code>configuration</code> section.
</p>

<p>
For example, to configure the <code>File</code> configuration backend:
</p>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>configuration<span class="br0">&#93;</span></span>
<span class="re1">type</span><span class="sy0">=</span><span class="re2">File</span>
<span class="re1">dirName</span> <span class="sy0">=</span><span class="re2"> /usr/local/lemonldap-ng/data/conf</span></pre>
<div class="notetip">See <a href="changeconfbackend.html" class="wikilink1" title="documentation:2.0:changeconfbackend">How to change configuration backend</a> to known how to change this.
</div>
</div>
<!-- EDIT2 SECTION "Backends" [39-1047] -->
<h2 class="sectionedit3" id="manager">Manager</h2>
<div class="level2">

<p>
Most of configuration can be done trough LemonLDAP::NG Manager (by default <a href="http://manager.example.com" class="urlextern" title="http://manager.example.com"  rel="nofollow">http://manager.example.com</a>).
</p>

<p>
By default, Manager is protected to allow only the demonstration user “dwho”.
</p>
<div class="noteimportant">This user will not be available anymore if you configure a new authentication backend! Remember to change the access rule in Manager virtual host to allow new administrators.
</div>
<p>
If you can not access the Manager anymore, you can unprotect it by editing <code>lemonldap-ng.ini</code> and changing the <code>protection</code> parameter:
</p>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>manager<span class="br0">&#93;</span></span>
&nbsp;
# Manager protection: by default, the manager is protected by a demo account.
# You can protect it :
# * by Apache itself,
# * by the parameter 'protection' which can take one of the following
# values :
#   * authenticate : all authenticated users can access
#   * manager      : manager is protected like other virtual hosts: you
#                    have to set rules in the corresponding virtual host
#   * rule: &lt;rule&gt; : you can set here directly the rule to apply
#   * none         : no protection</pre>
<div class="notetip">See <a href="managerprotection.html" class="wikilink1" title="documentation:2.0:managerprotection">Manager protection documentation</a> to know how to use Apache modules or <abbr title="LemonLDAP::NG">LL::NG</abbr> to manage access to Manager.
</div>
<p>
The Manager displays main branches:
</p>
<ul>
<li class="level1"><div class="li"> <strong>General Parameters</strong>: Authentication modules, portal, etc.</div>
</li>
<li class="level1"><div class="li"> <strong>Variables</strong>: User information, macros and groups used to fill <abbr title="Single Sign On">SSO</abbr> session</div>
</li>
<li class="level1"><div class="li"> <strong>Virtual Hosts</strong>: Access rules, headers, etc.</div>
</li>
<li class="level1"><div class="li"> <strong><abbr title="Security Assertion Markup Language">SAML</abbr> 2 Service</strong>: <abbr title="Security Assertion Markup Language">SAML</abbr> metadata administration</div>
</li>
<li class="level1"><div class="li"> <strong><abbr title="Security Assertion Markup Language">SAML</abbr> identity providers</strong>: Registered IDP</div>
</li>
<li class="level1"><div class="li"> <strong><abbr title="Security Assertion Markup Language">SAML</abbr> service providers</strong>: Registered SP</div>
</li>
<li class="level1"><div class="li"> <strong>OpenID Connect Service</strong>: OpenID Connect service configuration</div>
</li>
<li class="level1"><div class="li"> <strong>OpenID Connect Providers</strong>: Registered OP</div>
</li>
<li class="level1"><div class="li"> <strong>OpenID Connect Relying Parties</strong>: Registered RP</div>
</li>
</ul>

<p>
LemonLDAP::NG configuration is mainly a key/value structure, so Manager will present all keys into a structured tree. A click on a key will display the associated value.
</p>

<p>
When all modifications are done, click on <code>Save</code> to store configuration.
</p>
<div class="notewarning">LemonLDAP::NG will do some checks on configuration and display errors and warnings if any. Configuration <strong>is not saved</strong> if errors occur.
</div>
</div>
<!-- EDIT3 SECTION "Manager" [1048-3236] -->
<h2 class="sectionedit4" id="configuration_text_editor">Configuration text editor</h2>
<div class="level2">

<p>
LemonLDAP::NG provide a script that allows one to edit configuration without graphical interface, this script is called <code>lmConfigEditor</code> and is stored in the LemonLDAP::NG bin/ directory, for example /usr/share/lemonldap-ng/bin:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lmConfigEditor</pre>
<div class="notetip">This script must be run as root, it will then use the Apache user and group to access configuration.
</div>
<p>
The script uses the <code>editor</code> system command, that links to your favorite editor. To change it:
</p>
<pre class="code">update-alternatives --config editor</pre>

<p>
The configuration is displayed as a big Perl Hash, that you can edit:
</p>
<pre class="code file perl"><span class="re0">$VAR1</span> <span class="sy0">=</span> <span class="br0">&#123;</span>
          <span class="st_h">'ldapAuthnLevel'</span> <span class="sy0">=&gt;</span> <span class="st_h">'2'</span><span class="sy0">,</span>
          <span class="st_h">'notificationWildcard'</span> <span class="sy0">=&gt;</span> <span class="st_h">'allusers'</span><span class="sy0">,</span>
          <span class="st_h">'loginHistoryEnabled'</span> <span class="sy0">=&gt;</span> <span class="st_h">'1'</span><span class="sy0">,</span>
          <span class="st_h">'key'</span> <span class="sy0">=&gt;</span> <span class="st_h">'q`e)kJE%&lt;&amp;wm&gt;uaA'</span><span class="sy0">,</span>
          <span class="st_h">'samlIDPSSODescriptorSingleSignOnServiceHTTPPost'</span> <span class="sy0">=&gt;</span> <span class="st_h">'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST;#PORTAL#/saml/singleSignOn;'</span><span class="sy0">,</span>
          <span class="st_h">'portalSkin'</span> <span class="sy0">=&gt;</span> <span class="st_h">'pastel'</span><span class="sy0">,</span>
          <span class="st_h">'failedLoginNumber'</span> <span class="sy0">=&gt;</span> <span class="st_h">'5'</span><span class="sy0">,</span>
          <span class="sy0">...</span>
          <span class="br0">&#125;</span><span class="sy0">;</span></pre>

<p>
If a modification is done, the configuration is saved with a new configuration number. Else, current configuration is kept.
</p>

</div>
<!-- EDIT4 SECTION "Configuration text editor" [3237-4465] -->
<h2 class="sectionedit5" id="command_line_interface_cli">Command Line Interface (CLI)</h2>
<div class="level2">

<p>
LemonLDAP::NG provide a script that allows one to edit configuration items in non interactive mode. This script is called <code>lemonldap-ng-cli</code> and is stored in the LemonLDAP::NG bin/ directory, for example /usr/share/lemonldap-ng/bin:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli</pre>
<div class="notetip">This script must be run as root, it will then use the Apache user and group to access configuration.
</div>
<p>
To see available actions, do:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli help</pre>

<p>
You can force an update of configuration cache with:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli update-cache</pre>

<p>
To get information about current configuration:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli info</pre>

<p>
To view a configuration parameter, for example portal <abbr title="Uniform Resource Locator">URL</abbr>:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli get portal</pre>

<p>
To set a parameter, for example domain:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli set domain example.org</pre>

<p>
You can use accessors (options) to change the behavior:
</p>
<ul>
<li class="level1"><div class="li"> -sep: separator of hierarchical values (by default: /).</div>
</li>
<li class="level1"><div class="li"> -iniFile: the lemonldap-ng.ini file to use if not default value.</div>
</li>
<li class="level1"><div class="li"> -yes: do not prompt for confirmation before saving new configuration.</div>
</li>
<li class="level1"><div class="li"> -cfgNum: the configuration number. If not set, it will use the latest configuration.</div>
</li>
<li class="level1"><div class="li"> -force: set it to 1 to save a configuration earlier than latest.</div>
</li>
</ul>

<p>
Some examples:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli -cfgNum 10 get exportedHeaders/test1.example.com
/usr/share/lemonldap-ng/bin/lemonldap-ng-cli -yes 1 set notification 1
/usr/share/lemonldap-ng/bin/lemonldap-ng-cli -sep &#039;,&#039; get macros,_whatToTrace</pre>
<div class="notetip">See <a href="cli_examples.html" class="wikilink1" title="documentation:2.0:cli_examples">other examples</a>.
</div>
</div>
<!-- EDIT5 SECTION "Command Line Interface (CLI)" [4466-6260] -->
<h2 class="sectionedit6" id="apache">Apache</h2>
<div class="level2">
<div class="noteimportant">LemonLDAP::NG does not manage Apache configuration
</div>
<p>
LemonLDAP::NG ships 3 Apache configuration files:
</p>
<ul>
<li class="level1"><div class="li"> <strong>portal-apache2.conf</strong>: Portal virtual host, with SOAP/REST end points</div>
</li>
<li class="level1"><div class="li"> <strong>manager-apache2.conf</strong>: Manager virtual host</div>
</li>
<li class="level1"><div class="li"> <strong>handler-apache2.conf</strong> : Handler declaration, reload and sample virtual hosts</div>
</li>
</ul>

<p>
See <a href="configapache.html" class="wikilink1" title="documentation:2.0:configapache">how to deploy them</a>.
</p>

</div>
<!-- EDIT6 SECTION "Apache" [6261-6659] -->
<h3 class="sectionedit7" id="portal">Portal</h3>
<div class="level3">

<p>
In Portal virtual host, you will find several configuration parts:
</p>
<ul>
<li class="level1"><div class="li"> Standard virtual host directives, to serve portal pages:</div>
</li>
</ul>
<pre class="code file apache">    <span class="kw1">ServerName</span> auth.example.com
&nbsp;
    <span class="co1"># DocumentRoot</span>
    <span class="kw1">DocumentRoot</span> /usr/local/lemonldap-ng/htdocs/portal/
    &lt;<span class="kw3">Directory</span> /usr/local/lemonldap-ng/htdocs/portal/&gt;
        <span class="kw1">Require</span> <span class="kw2">all</span> granted
        <span class="kw1">Options</span> +ExecCGI +<span class="kw2">FollowSymLinks</span>
    &lt;/<span class="kw3">Directory</span>&gt;
    <span class="co1"># For performances, you can put static html files: simply put the HTML</span>
    <span class="co1"># result (example: /oauth2/checksession.html) as static file. Then</span>
    <span class="co1"># uncomment the following line.</span>
    <span class="co1"># RewriteCond &quot;%{REQUEST_FILENAME}&quot; &quot;!\.html$&quot;</span>
    <span class="kw1">RewriteCond</span> <span class="st0">&quot;%{REQUEST_FILENAME}&quot;</span> <span class="st0">&quot;!^/(?:(?:static|javascript|favicon).*|.*<span class="es0">\.</span>fcgi)$&quot;</span>
    <span class="kw1">RewriteRule</span> <span class="st0">&quot;^/(.+)$&quot;</span> <span class="st0">&quot;/index.fcgi/$1&quot;</span> [PT]
&nbsp;
    <span class="co1"># Note that Content-Security-Policy header is generated by portal itself</span>
    &lt;<span class="kw3">Files</span> *.fcgi&gt;
        <span class="kw1">SetHandler</span> fcgid-<span class="kw1">script</span>
        <span class="co1"># For Authorization header to be passed, please uncomment one of the following:</span>
        <span class="co1"># for Apache &gt;= 2.4.13</span>
        <span class="co1">#CGIPassAuth On</span>
        <span class="co1"># for Apache &lt; 2.4.13</span>
        <span class="co1">#RewriteCond %{HTTP:Authorization} ^(.*)</span>
        <span class="co1">#RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]</span>
        <span class="kw1">Options</span> +ExecCGI
    &lt;/<span class="kw3">Files</span>&gt;
&nbsp;
    <span class="co1"># Static files</span>
    <span class="kw1">Alias</span> /static/ __PORTALSTATICDIR__/
    &lt;<span class="kw3">Directory</span> __PORTALSTATICDIR__&gt;
        <span class="kw1">Require</span> <span class="kw2">all</span> granted
        <span class="kw1">Options</span> +<span class="kw2">FollowSymLinks</span>
    &lt;/<span class="kw3">Directory</span>&gt;
    &lt;<span class="kw3">Location</span> /static/&gt;
        &lt;<span class="kw3">IfModule</span> mod_expires.c&gt;
            <span class="kw1">ExpiresActive</span> <span class="kw2">On</span>
            <span class="kw1">ExpiresDefault</span> <span class="st0">&quot;access plus 1 month&quot;</span>
        &lt;/<span class="kw3">IfModule</span>&gt;
    &lt;/<span class="kw3">Location</span>&gt;
&nbsp;
    &lt;<span class="kw3">IfModule</span> mod_dir.c&gt;
        <span class="kw1">DirectoryIndex</span> index.fcgi index.html
    &lt;/<span class="kw3">IfModule</span>&gt;</pre>
<ul>
<li class="level1"><div class="li"> REST/SOAP end points (disabled by default):</div>
</li>
</ul>
<pre class="code file apache">    <span class="co1"># REST/SOAP functions for sessions management (disabled by default)</span>
    &lt;<span class="kw3">Location</span> /index.fcgi/adminSessions&gt;
        <span class="kw1">Require</span> <span class="kw2">all</span> denied
    &lt;/<span class="kw3">Location</span>&gt;
&nbsp;
    <span class="co1"># REST/SOAP functions for sessions access (disabled by default)</span>
    &lt;<span class="kw3">Location</span> /index.fcgi/sessions&gt;
        <span class="kw1">Require</span> <span class="kw2">all</span> denied
    &lt;/<span class="kw3">Location</span>&gt;
&nbsp;
    <span class="co1"># REST/SOAP functions for configuration access (disabled by default)</span>
    &lt;<span class="kw3">Location</span> /index.fcgi/config&gt;
        <span class="kw1">Require</span> <span class="kw2">all</span> denied
    &lt;/<span class="kw3">Location</span>&gt;
&nbsp;
    <span class="co1"># REST/SOAP functions for notification insertion (disabled by default)</span>
    &lt;<span class="kw3">Location</span> /index.fcgi/notification&gt;
        <span class="kw1">Require</span> <span class="kw2">all</span> denied
    &lt;/<span class="kw3">Location</span>&gt;</pre>

</div>
<!-- EDIT7 SECTION "Portal" [6660-9007] -->
<h3 class="sectionedit8" id="manager1">Manager</h3>
<div class="level3">

<p>
Manager virtual host is used to serve configuration interface and local documentation. It is run as a FastCGI application:
</p>
<pre class="code file apache">    <span class="co1"># FASTCGI CONFIGURATION</span>
    <span class="co1"># ---------------------</span>
&nbsp;
    <span class="co1"># 1) URI management</span>
    <span class="kw1">RewriteEngine</span> <span class="kw2">on</span>
&nbsp;
    <span class="kw1">RewriteRule</span> <span class="st0">&quot;^/$&quot;</span> <span class="st0">&quot;/psgi/manager-server.fcgi&quot;</span> [PT]
    <span class="co1"># For performances, you can delete the previous RewriteRule line after</span>
    <span class="co1"># puttings html files: simply put the HTML results of different modules</span>
    <span class="co1"># (configuration, sessions, notifications) as manager.html, sessions.html,</span>
    <span class="co1"># notifications.html and uncomment the 2 following lines:</span>
    <span class="co1"># DirectoryIndex manager.html</span>
    <span class="co1"># RewriteCond &quot;%{REQUEST_FILENAME}&quot; &quot;!\.html$&quot;</span>
&nbsp;
    <span class="co1"># REST URLs</span>
    <span class="kw1">RewriteCond</span> <span class="st0">&quot;%{REQUEST_FILENAME}&quot;</span> <span class="st0">&quot;!^/(?:static|doc|lib).*&quot;</span>
    <span class="kw1">RewriteRule</span> <span class="st0">&quot;^/(.+)$&quot;</span> <span class="st0">&quot;/psgi/manager-server.fcgi/$1&quot;</span> [PT]
&nbsp;
    <span class="kw1">Alias</span> /psgi/ /var/lib/lemonldap-ng/manager/psgi/
&nbsp;
    <span class="co1"># 2) FastCGI engine</span>
&nbsp;
    <span class="co1"># You can choose any FastCGI system. Here is an example using mod_fcgid</span>
    <span class="co1"># mod_fcgid configuration</span>
    &lt;<span class="kw3">Directory</span> /var/lib/lemonldap-ng/manager/psgi/&gt;
        <span class="kw1">SetHandler</span> fcgid-<span class="kw1">script</span>
        <span class="kw1">Options</span> +ExecCGI
    &lt;/<span class="kw3">Directory</span>&gt;
&nbsp;
    <span class="co1"># If you want to use mod_fastcgi, replace lines below by:</span>
    <span class="co1">#FastCgiServer /var/lib/lemonldap-ng/manager/psgi/manager-server.fcgi</span>
&nbsp;
    <span class="co1"># Or if you prefer to use CGI, use /psgi/manager-server.cgi instead of</span>
    <span class="co1"># /psgi/manager-server.fcgi and adapt the rewrite rules.</span></pre>

<p>
Configuration interface access is not protected by Apache but by LemonLDAP::NG itself (see <code>lemonldap-ng.ini</code>).
</p>

</div>
<!-- EDIT8 SECTION "Manager" [9008-10551] -->
<h3 class="sectionedit9" id="handler">Handler</h3>
<div class="level3">
<ul>
<li class="level1"><div class="li"> Load Handler in Apache memory:</div>
</li>
</ul>
<pre class="code file apache">PerlOptions +GlobalRequest
PerlModule Lemonldap::NG::Handler::Apache2</pre>
<ul>
<li class="level1"><div class="li"> Catch error pages:</div>
</li>
</ul>
<pre class="code file apache"><span class="kw1">ErrorDocument</span> <span class="nu0">403</span> http://auth.example.com/lmerror/<span class="nu0">403</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">404</span> http://auth.example.com/lmerror/<span class="nu0">404</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">500</span> http://auth.example.com/lmerror/<span class="nu0">500</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">502</span> http://auth.example.com/lmerror/<span class="nu0">502</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">503</span> http://auth.example.com/lmerror/<span class="nu0">503</span></pre>
<ul>
<li class="level1"><div class="li"> Reload virtual host:</div>
</li>
</ul>
<pre class="code file apache">&lt;<span class="kw3">VirtualHost</span> *:<span class="nu0">80</span>&gt;
    <span class="kw1">ServerName</span> reload.example.com
&nbsp;
    <span class="co1"># Configuration reload mechanism (only 1 per physical server is</span>
    <span class="co1"># needed): choose your URL to avoid restarting Apache when</span>
    <span class="co1"># configuration change</span>
    &lt;<span class="kw3">Location</span> /reload&gt;
        <span class="kw1">Order</span> <span class="kw1">deny</span>,<span class="kw1">allow</span>
        <span class="kw1">Deny</span> from <span class="kw2">all</span>
        <span class="kw1">Allow</span> from 127.0.0.0/<span class="nu0">8</span>
        <span class="kw1">SetHandler</span> perl-<span class="kw1">script</span>
        PerlResponseHandler Lemonldap::NG::Handler::Apache2-&gt;reload
    &lt;/<span class="kw3">Location</span>&gt;
&nbsp;
    <span class="co1"># Uncomment this to activate status module</span>
    <span class="co1">#&lt;Location /status&gt;</span>
    <span class="co1">#    Order deny,allow</span>
    <span class="co1">#    Deny from all</span>
    <span class="co1">#    Allow from 127.0.0.0/8</span>
    <span class="co1">#    SetHandler perl-script</span>
    <span class="co1">#    PerlResponseHandler Lemonldap::NG::Handler::Apache2-&gt;status</span>
    <span class="co1">#&lt;/Location&gt;</span>
&nbsp;
&lt;/<span class="kw3">VirtualHost</span>&gt;</pre>

<p>
Then, to protect a standard virtual host, the only configuration line to add is:
</p>
<pre class="code file apache">PerlHeaderParserHandler Lemonldap::NG::Handler::Apache2</pre>

</div>
<!-- EDIT9 SECTION "Handler" [10552-11941] -->
<h2 class="sectionedit10" id="nginx">Nginx</h2>
<div class="level2">
<div class="noteimportant">LemonLDAP::NG does not manage Nginx configuration
</div>
<p>
LemonLDAP::NG ships 3 Nginx configuration files:
</p>
<ul>
<li class="level1"><div class="li"> <strong>portal-nginx.conf</strong>: Portal virtual host, with REST/SOAP end points</div>
</li>
<li class="level1"><div class="li"> <strong>manager-nginx.conf</strong>: Manager virtual host</div>
</li>
<li class="level1"><div class="li"> <strong>handler-nginx.conf</strong> : Handler reload virtual hosts</div>
</li>
</ul>

<p>
See <a href="confignginx.html" class="wikilink1" title="documentation:2.0:confignginx">how to deploy them</a>.
</p>
<div class="notewarning"><a href="fastcgiserver.html" class="wikilink1" title="documentation:2.0:fastcgiserver">LL::NG FastCGI</a> server must be loaded separately.
</div>
</div>
<!-- EDIT10 SECTION "Nginx" [11942-12395] -->
<h3 class="sectionedit11" id="portal1">Portal</h3>
<div class="level3">

<p>
In Portal virtual host, you will find several configuration parts:
</p>
<ul>
<li class="level1"><div class="li"> Standard virtual host directives, to serve portal pages:</div>
</li>
</ul>
<pre class="code file nginx">server {
  listen 80;
  server_name auth.example.com;
  root /var/lib/lemonldap-ng/portal/;
  if ($uri !~ ^/((static|javascript|favicon).*|.*\.psgi)) {
    rewrite ^/(.*)$ /index.psgi/$1 break;
  }
&nbsp;
  location ~ \.psgi(?:$|/) {
    # Note that Content-Security-Policy header is generated by portal itself
    include /etc/nginx/fastcgi_params;
    fastcgi_pass unix:__FASTCGISOCKDIR__/llng-fastcgi.sock;
    fastcgi_param LLTYPE psgi;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_split_path_info ^(.*\.psgi)(/.*)$;
    fastcgi_param PATH_INFO  $fastcgi_path_info;
    # Uncomment this if you use Auth SSL:
    #map $ssl_client_s_dn  $ssl_client_s_dn_cn {
    #  default           &quot;&quot;;
    #  ~/CN=(?&lt;CN&gt;[^/]+) $CN;
    #}
    #fastcgi_param  SSL_CLIENT_S_DN_CN $ssl_client_s_dn_cn
  }
&nbsp;
  index index.psgi;
  location / {
    try_files $uri $uri/ =404;
&nbsp;
    # Uncomment this if you use https only
    #add_header Strict-Transport-Security &quot;15768000&quot;;
  }
&nbsp;
  location /static/ {
    alias __PORTALSTATICDIR__;
  }
}</pre>
<ul>
<li class="level1"><div class="li"> REST/SOAP end points (inactivated by default):</div>
</li>
</ul>
<pre class="code file nginx">  # REST/SOAP functions for sessions management (disabled by default)
  location /index.psgi/adminSessions {
    deny all;
  }
&nbsp;
  # REST/SOAP functions for sessions access (disabled by default)
  location /index.psgi/sessions {
    deny all;
  }
&nbsp;
  # REST/SOAP functions for configuration access (disabled by default)
  location /index.psgi/config {
    deny all;
  }
&nbsp;
  # REST/SOAP functions for notification insertion (disabled by default)
  location /index.psgi/notification {
    deny all;
  }</pre>

</div>
<!-- EDIT11 SECTION "Portal" [12396-14187] -->
<h3 class="sectionedit12" id="manager2">Manager</h3>
<div class="level3">

<p>
Manager virtual host is used to serve configuration interface and local documentation.
</p>
<pre class="code file nginx">server {
  listen 80;
  server_name manager.example.com;
  root /usr/share/lemonldap-ng/manager/;
&nbsp;
  if ($uri !~ ^/(static|doc|lib|javascript)) {
    rewrite ^/(.*)$ /manager.psgi/$1 break;
  }
&nbsp;
  location /manager.psgi {
    include /etc/nginx/fastcgi_params;
    fastcgi_pass unix:/var/run/llng-fastcgi-server/llng-fastcgi.sock;
    fastcgi_param LLTYPE manager;
    fastcgi_param SCRIPT_NAME /manager.psgi;
  }
&nbsp;
  location / {
    index manager.psgi;
    try_files $uri $uri/ =404;
  }
}</pre>

<p>
By default, configuration interface access is not protected by Nginx but by LemonLDAP::NG itself (see <code>lemonldap-ng.ini</code>).
</p>

</div>
<!-- EDIT12 SECTION "Manager" [14188-14933] -->
<h3 class="sectionedit13" id="handler1">Handler</h3>
<div class="level3">

<p>
Nginx handler is provided by the <a href="fastcgiserver.html" class="wikilink1" title="documentation:2.0:fastcgiserver">LemonLDAP::NG FastCGI server</a>.
</p>
<ul>
<li class="level1"><div class="li"> Handle errors:</div>
</li>
</ul>
<pre class="code file nginx">error_page 403 http://auth.example.com/lmerror/403;
error_page 404 http://auth.example.com/lmerror/404;
error_page 500 http://auth.example.com/lmerror/500;
error_page 502 http://auth.example.com/lmerror/502;
error_page 503 http://auth.example.com/lmerror/503;</pre>
<ul>
<li class="level1"><div class="li"> Reload virtual host:</div>
</li>
</ul>
<pre class="code file nginx">server {
  listen 80;
  server_name reload.example.com;
  root /var/www/html;
&nbsp;
  location = /reload {
    allow 127.0.0.1;
    deny all;
    include /etc/nginx/fastcgi_params;
    fastcgi_pass unix:/var/run/llng-fastcgi-server/llng-fastcgi.sock;
    fastcgi_param LLTYPE reload;
  }
&nbsp;
  # Other requests
  location / {
    deny all;
  }
&nbsp;
  # Uncomment this if status is enabled
  #location = /status {
  #  allow 127.0.0.1;
  #  deny all;
  #  include /etc/nginx/fastcgi_params;
  #  fastcgi_pass unix:/var/run/llng-fastcgi-server/llng-fastcgi.sock;
  #  fastcgi_param LLTYPE status;
  #}
}</pre>

<p>
Then, to protect a standard virtual host, you must insert this (or create an included file):
</p>
<pre class="code file nginx">  # Insert $_user in logs
  include /etc/lemonldap-ng/nginx-lmlog.conf;
  access_log /var/log/nginx/access.log lm_combined;
&nbsp;
  # Internal call to FastCGI server
  location = /lmauth {
    internal;
    include /etc/nginx/fastcgi_params;
    fastcgi_pass unix:/var/run/llng-fastcgi-server/llng-fastcgi.sock;
    fastcgi_pass_request_body  off;
    fastcgi_param CONTENT_LENGTH &quot;&quot;;
    fastcgi_param HOST $http_host;
    fastcgi_param X_ORIGINAL_URI  $request_uri;
  }
&nbsp;
  # Client requests
  location / {
    auth_request /lmauth;
    auth_request_set $lmremote_user $upstream_http_lm_remote_user;
    auth_request_set $lmlocation $upstream_http_location;
    error_page 401 $lmlocation;
    try_files $uri $uri/ =404;
&nbsp;
    # Set REMOTE_USER (for FastCGI apps only)
    #fastcgi_param REMOTE_USER $lmremote_user
&nbsp;
    ##################################
    # PASSING HEADERS TO APPLICATION #
    ##################################
&nbsp;
    # IF LUA IS SUPPORTED
    #include /path/to/nginx-lua-headers.conf
&nbsp;
    # ELSE
    # Set manually your headers
    #auth_request_set $authuser $upstream_http_auth_user;
    #proxy_set_header Auth-User $authuser;
    # OR
    #fastcgi_param HTTP_AUTH_USER $authuser;
&nbsp;
    # Then (if LUA not supported), change cookie header to hide LLNG cookie
    #auth_request_set $lmcookie $upstream_http_cookie;
    #proxy_set_header Cookie: $lmcookie;
    # OR
    #fastcgi_param HTTP_COOKIE $lmcookie;
&nbsp;
    # Insert then your configuration (fastcgi_* or proxy_*)</pre>

</div>
<!-- EDIT13 SECTION "Handler" [14934-18015] -->
<h2 class="sectionedit14" id="configuration_reload">Configuration reload</h2>
<div class="level2">
<div class="noteclassic">As Handlers keep configuration in cache, when configuration change, it should be updated in Handlers. An Apache restart will work, but LemonLDAP::NG offers the mean to reload them through an HTTP request. Configuration reload will then be effective in less than 10 minutes. If you want to change this timeout, set <code>checkTime = 240</code> in your lemonldap-ng.ini file <em>(values in seconds)</em>
</div>
<p>
After configuration is saved by Manager, LemonLDAP::NG will try to reload configuration on distant Handlers by sending an HTTP request to the servers. The servers and URLs can be configured in Manager, <code>General Parameters</code> &gt; <code>reload configuration URLs</code>: keys are server names or <abbr title="Internet Protocol">IP</abbr> the requests will be sent to, and values are the requested URLs.
</p>

<p>
You also have a parameter to adjust the timeout used to request reload URLs, it is be default set to 5 seconds.
</p>

<p>
These parameters can be overwritten in LemonLDAP::NG ini file, in the section <code>apply</code>.
</p>
<div class="notetip">You only need a reload <abbr title="Uniform Resource Locator">URL</abbr> per physical servers, as Handlers share the same configuration cache on each physical server.
</div>
<p>
The <code>reload</code> target is managed in Apache or Nginx configuration, inside a virtual host protected by LemonLDAP::NG Handler (see below examples in Apache-&gt;handler or Nginx-&gt;Handler).
</p>
<div class="noteimportant">You must allow access to declared URLs to your Manager <abbr title="Internet Protocol">IP</abbr>.
</div><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>
<p>
Practical use case: configure reload in a <abbr title="LemonLDAP::NG">LL::NG</abbr> cluster. In this case you will have two servers (with <abbr title="Internet Protocol">IP</abbr> 1.1.1.1 and 1.1.1.2), but you can keep only one reload <abbr title="Uniform Resource Locator">URL</abbr> (reload.example.com):
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli -yes 1 addKey \
reloadUrls &#039;1.1.1.1&#039; &#039;http://reload.example.com/reload&#039; \
reloadUrls &#039;1.1.1.2&#039; &#039;http://reload.example.com/reload&#039;</pre>

<p>
You also need to adjust the protection of the reload vhost, for example:
</p>
<pre class="code file apache">    &lt;<span class="kw3">Location</span> /reload&gt;
        <span class="kw1">Require</span> ip <span class="nu0">127</span> ::<span class="nu0">1</span> 1.1.1.1 1.1.1.2
        <span class="kw1">SetHandler</span> perl-<span class="kw1">script</span>
        PerlResponseHandler Lemonldap::NG::Handler::ApacheMP2-&gt;reload
    &lt;/<span class="kw3">Location</span>&gt;</pre>

</div>
<!-- EDIT14 SECTION "Configuration reload" [18016-20299] -->
<h2 class="sectionedit15" id="local_file">Local file</h2>
<div class="level2">

<p>
LemonLDAP::NG configuration can be managed in a local file with <a href="http://en.wikipedia.org/wiki/INI_file" class="urlextern" title="http://en.wikipedia.org/wiki/INI_file"  rel="nofollow">INI format</a>. This file is called <code>lemonldap-ng.ini</code> and has the following sections:
</p>
<ul>
<li class="level1"><div class="li"> <strong>configuration</strong>: where configuration is stored</div>
</li>
<li class="level1"><div class="li"> <strong>apply</strong>: reload <abbr title="Uniform Resource Locator">URL</abbr> for distant Hanlders</div>
</li>
<li class="level1"><div class="li"> <strong>all</strong>: parameters for all modules</div>
</li>
<li class="level1"><div class="li"> <strong>portal</strong>: parameters only for Portal</div>
</li>
<li class="level1"><div class="li"> <strong>manager</strong>: parameters only for Manager</div>
</li>
<li class="level1"><div class="li"> <strong>handler</strong>: parameters only for Handler</div>
</li>
</ul>

<p>
When you set a parameter in <code>lemonldap-ng.ini</code>, it will override the parameter from the global configuration.
</p>

<p>
For example, to override configured skin for portal:
</p>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>portal<span class="br0">&#93;</span></span>
<span class="re1">portalSkin</span> <span class="sy0">=</span><span class="re2"> dark</span></pre>
<div class="notetip">You need to know the technical name of configuration parameter to do this. You can refer to <a href="parameterlist.html" class="wikilink1" title="documentation:2.0:parameterlist">parameter list</a> to find it.
</div>
</div>
<!-- EDIT15 SECTION "Local file" [20300-] --></div>
</body>
</html>