Skip to content

Commit

Permalink
Update documentation to include new features
Browse files Browse the repository at this point in the history
  • Loading branch information
@BrunoCoimbra @mambelli
BrunoCoimbra authored and mambelli committed Feb 25, 2025
1 parent daf62c8 commit 4ee4197
Show file tree
Hide file tree
Showing 2 changed files with 130 additions and 34 deletions.
30 changes: 27 additions & 3 deletions doc/factory/configuration.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,11 @@ <h3>Configuration</h3>
<li>
<a href="#reconfigure_hooks">Running pre/post reconfigure hooks</a>
</li>
<li>
<a href="#upgrade"
>Upgrading to GlideinWMS 3.11.x (development series)</a
>
</li>
</ol>
</div>
<div class="related">
Expand Down Expand Up @@ -1099,6 +1104,7 @@ <h3 class="western">Entry point arguments</h3>
using command line tools.
</li>
<li>
<a name="auth_method" />
<div class="xml">
&lt;glidein&gt;&lt;entries&gt;&lt;entry name=&quot;<i
>entry name</i
Expand Down Expand Up @@ -1176,9 +1182,6 @@ <h3 class="western">Entry point arguments</h3>
>(condorsubmit=(universe vanilla)(requirements
\&quot;(ISMINOSAFS=?=True)\&quot;))</tt
>'). <br />
NOTE: If the auth_method contains "+project_id" for a TeraGrid
entry, the string "(project=TG_PROJECT_ID)" will be added by the
Factory and populated with the project id passed in the request.
</li>
<li>
<div class="xml">
Expand Down Expand Up @@ -3216,6 +3219,27 @@ <h3 class="western">Running pre/post reconfigure hooks</h3>
as user
<pre>gfactory</pre>
. Only executable scripts will be executed.
<br />
<br />
</div>

<div>
<a name="upgrade" />
<h3 class="western">
Upgrading to GlideinWMS 3.11.x (development series)
</h3>
<p>
When upgrading to GlideinWMS 3.11.x, you will not need to make any
changes to your Factory configuration. However, you may want to
consider using the new
<a href="#auth_method"><code>auth_method</code></a> features that
allow to specify a combination of credential types and security
parameters.
</p>
<p>
The new Factory is back compatible with older versions of the
Frontend.
</p>
</div>

<div class="footer">
Expand Down
134 changes: 103 additions & 31 deletions doc/frontend/configuration.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,14 @@ <h3>Configuration</h3>
<li>
<a href="#reconfigure_hooks">Running pre/post reconfigure hooks</a>
</li>
<li>
<a href="#generators">GlideinWMS Generators</a>
</li>
<li>
<a href="#upgrade"
>Upgrading to GlideinWMS 3.11.x (development series)</a
>
</li>
</ol>
</div>
<div class="related">
Expand Down Expand Up @@ -237,11 +245,9 @@ <h2>Example Configuration</h2>
href_link="/site/disclaimer.html" /&gt;</a
><br /><br />
<a href="#security"
>&lt;security classad_proxy="/etc/grid-security/hostcert.pem"
comment="use hostcert here if not doing GSI authentication through
GWMS versions 3.6.5" idtoken_lifetime="24"
>&lt;security comment="use hostcert here if not doing GSI
authentication through GWMS versions 3.6.5" idtoken_lifetime="24"
idtoken_keyname="FRONTEND"
proxy_DN="/DC=org/DC=doegrids/OU=Services/CN=frontend-server.fnal.gov"
proxy_selection_plugin="CredentialsBasic"
security_name="frontenduser" sym_key="aes_256_cbc"&gt;</a
><br />
Expand Down Expand Up @@ -753,24 +759,26 @@ <h2 class="western"><a name="management"></a>Frontend Configuration</h2>

<div class="xml">
&lt;frontend&gt;&lt;security
proxy_DN=&quot;<i>/DC=org/DC=doegrids/OU=Service/CN=frontend/frontend1.my.org</i>&quot;
classad_proxy=&quot;<i>proxy_dir</i>&quot;
proxy_selection_plugin=&quot;<i>CredentialsBasic</i>&quot;
security_name=&quot;<i>vofrontend1</i>&quot;&gt;
</div>
<p>
Grid proxy to use is located in the classad_proxy directory and
you must specify the full path to the proxy. security_name
signifies the name under which the Frontend is registered with the
factory. <br />
The idtoken_lifetime is used to indicate the number of hours the
idtoken is valid. The idtoken is used on the worker node to
connect back to the VO collector. It is possible to set the key
used to generate these token by using the idtoken_keyname
An HTCondor IDTOKEN is generated by the Frontend and sent along
with the Glidein to be used on the worker node to connect back
with the VO collector. The idtoken_lifetime is used to indicate
the number of hours the idtoken is valid. It is possible to set
the key used to generate these tokens by using the idtoken_keyname
parameter.
<br />For A GSI free configuration, set the classad_proxy to
"/etc/grid-security/hostcert.pem" and set up a scitoken in the
&lt;credentials&gt; section below.
</p>

<p>
<i>
NOTE: <code>classad_proxy</code> and <code>proxy_DN</code> are
now deprecated. Keeping this attributes on the configuration
file will not cause errors, but they will be ignored. Future
versions of the Frontend may remove them completely, causing
errors if they are still present.
</i>
</p>
</li>
<li>
Expand Down Expand Up @@ -803,15 +811,6 @@ <h2 class="western"><a name="management"></a>Frontend Configuration</h2>
following:
</p>
<ul>
<li>
<b>grid_proxy</b>: A x509 proxy stored in the
<i>absfname</i> location.
</li>
<li>
<b>cert_pair</b>: A x509 certificate pair with the cert in the
<i>absfname</i> location and the certkey in the
<i>keyabsfname</i> location.
</li>
<li>
<b>key_pair</b>: A key pair stored with the public key in
<i>absfname</i> location and the private key in
Expand Down Expand Up @@ -843,7 +842,22 @@ <h2 class="western"><a name="management"></a>Frontend Configuration</h2>
<i>context</i> attribute. When using generators, the type of the
generated credential must be specified in the context.
</li>
<li>
<b>[LEGACY] grid_proxy</b>: A x509 proxy stored in the
<i>absfname</i> location.
</li>
<li>
<b>[LEGACY] cert_pair</b>: A x509 certificate pair with the cert
in the <i>absfname</i> location and the certkey in the
<i>keyabsfname</i> location.
</li>
</ul>
<p>
<i>
LEGACY credential types are only supported if the underlying
HTCondor version supports them.
</i>
</p>
<p>
Pool index length and list allows the admin to configure a list of
credentials without having to list each one of them. The files
Expand Down Expand Up @@ -878,18 +892,21 @@ <h2 class="western"><a name="management"></a>Frontend Configuration</h2>
USERNAME@HOST:PORT string of the <i>gatekeeper</i> attribute. The
username has to be specified in at least one of these two places.
<br /><br />
The <i>context</i> attribute is used to pass additional
information to a generator. This attribute expects a dictionary in
JSON format. Built-in generators expect specific keys. Refer to
their documentation for more information.
The <i>context</i> attribute is only used for generators. It
expects a dictionary with the type of the generated credential and
can include other arbitrary key/value pairs. Built-in generators
require specific keys to be present in the context dictionary.
Please refer
<a href="#generators">generators documentation</a> for more
information.
</p>
</li>
<li>
<p>
<a name="parameters" />
</p>
<div class="xml">
&lt;frontend&gt;&lt;parameters&gt;&lt;parameter
&lt;frontend&gt;&lt;security&gt;&lt;parameters&gt;&lt;parameter
name=&quot;<i>parameter_name</i>&quot;
value=&quot;<i>value</i>&quot; type=&quot;<i>string</i>&quot;
context=&quot;<i>{"key": "value", "type": "<i>param_type</i>"}</i
Expand Down Expand Up @@ -934,6 +951,15 @@ <h2 class="western"><a name="management"></a>Frontend Configuration</h2>
generated parameter must be specified in the context.
</li>
</ul>
<p>
The <i>context</i> attribute is only used for generators. It
expects a dictionary with the type of the generated credential and
can include other arbitrary key/value pairs. Built-in generators
require specific keys to be present in the context dictionary.
Please refer
<a href="#generators">generators documentation</a> for more
information.
</p>
</li>
<li>
<p>
Expand Down Expand Up @@ -2764,6 +2790,52 @@ <h4>Built-in Generators</h4>
</table>
</div>

<div>
<a name="upgrade" />
<h3 class="western">
Upgrading to GlideinWMS 3.11.x (development series)
</h3>
<p>
When upgrading to GlideinWMS 3.11.x, you will need to update your
configuration files to make them compatible with the new version. You
may also want to make further changes to take advantage of the new
features inroduced in this version. Here is a summary of the changes
you need to make to your configuration files:
</p>
<ul>
<li>
You will need to update the <code>proxy_selection_plugin</code> in
the <code>security</code> section of your configuration file to
<code>CredentialsBasic</code>. All other plugins have been
deprecated and will be removed in future versions.
</li>
<li>
If you specify parameters (e.g. <code>project_id</code>) in as
credential qualifiers, you will need to redefine them as
<a href="#parameters">security parameters</a>. This new feature
allows you to define parameters orthogonal to credentials, and will
be considered for all credentials in a group. Note that security
parameters are no longer automatically bundled with the credentials
and should be specified explicitly.
</li>
<li>
Callout scripts are now deprecated. We recommend that you
reimplement them using the new
<a href="#generators">GlideinWMS Generators</a> framework. If you
want to continue using callouts, you can use the built-in
<code>LegacyGenerator</code> to wrap your callout scripts and use
them as generators. This will allow you to continue using your
existing callout scripts without having to rewrite them.
</li>
<li>
Make sure that the Factories in your configuration files are
compatible with the new version of GlideinWMS. Factories older than
3.11 will not be able to communicate with the new Frontend due to
changes in the ClassAds protocol.
</li>
</ul>
</div>

<div class="footer">
Banner image by
<a href="http://www.flickr.com/people/leafwarbler/">Madhusudan Katti</a>
Expand Down

0 comments on commit 4ee4197

Please sign in to comment.