-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathadmin.html
More file actions
263 lines (242 loc) · 16.1 KB
/
admin.html
File metadata and controls
263 lines (242 loc) · 16.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Admin Guide — GEOPM documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/colon_scheme_fix.js?v=ca089989"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Security Guide" href="security.html" />
<link rel="prev" title="Spack Guide" href="spack.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
GEOPM
<img src="https://geopm.github.io/images/geopm-logo-clear.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="overview.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install Guide</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Admin Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#linux-integration">Linux Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="#geopm-service-files">GEOPM Service Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuring-access-lists">Configuring Access Lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuring-systemd-unit-file">Configuring Systemd Unit File</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-msr-driver">The MSR Driver</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="security.html">Security Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="user_guides.html">User Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="contrib.html">Contributor Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="devel.html">Developer Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="publications.html">Publications</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="releases.html">Releases</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">GEOPM</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Admin Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/admin.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="admin-guide">
<h1>Admin Guide<a class="headerlink" href="#admin-guide" title="Link to this heading"></a></h1>
<p>This guide covers GEOPM’s integration with the Linux OS, directories influenced
by GEOPM, the utilization of files within those directories, and a command-line
tool for configuring the GEOPM Service. For further details, explore the
subsequent sections:</p>
<ul class="simple">
<li><p><a class="reference internal" href="install.html"><span class="doc">Install Guide</span></a></p></li>
<li><p><a class="reference internal" href="security.html"><span class="doc">Security Guide</span></a></p></li>
</ul>
<section id="linux-integration">
<h2>Linux Integration<a class="headerlink" href="#linux-integration" title="Link to this heading"></a></h2>
<p>The GEOPM Service integrates seamlessly with the Linux OS through Systemd. It is
packaged within the <code class="docutils literal notranslate"><span class="pre">geopmd</span></code> binary package, and administrators can install it
using their respective package management systems. Use <code class="docutils literal notranslate"><span class="pre">systemctl</span></code> to interact
with the <code class="docutils literal notranslate"><span class="pre">geopm</span></code> Systemd Unit.</p>
<p><strong>Systemctl Command Behavior</strong></p>
<ul>
<li><p><strong>start</strong>:</p>
<p>Starts the GEOPM Access Service. All required state files in <cite>/run/geopm</cite> are
initialized, and the service begins accepting client connections. Any stale
session files from previous runs are cleaned up as part of startup.</p>
</li>
<li><p><strong>stop</strong>:</p>
<p>Stops the GEOPM Access Service. All active client sessions are closed
gracefully before the service terminates. This includes restoring any hardware
controls (such as power limits) to their default or saved state, and cleaning
up session files in <cite>/run/geopm</cite>. The write-mode session (if any) is closed
first to ensure hardware state is restored.</p>
</li>
<li><p><strong>restart</strong>:</p>
<p>Re-initialize the service. Similar to running <code class="docutils literal notranslate"><span class="pre">stop</span></code> followed by <code class="docutils literal notranslate"><span class="pre">start</span></code>,
except that all sessions remain open through the process and controls are not
restored.</p>
</li>
<li><p><strong>enable</strong>:</p>
<p>Configures the GEOPM Access Service to start automatically at boot. This does
not immediately start the service, but ensures it will be started on the next
system boot.</p>
</li>
</ul>
<p><strong>Note:</strong>
The service is robust to unexpected shutdowns. If the geopmd process ends for
any reason, all state required to restart is preserved. To be certain that all
controls are restored to their original configuration, the administrator should
run <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">stop</span> <span class="pre">geopm</span></code>. Administrators can monitor the system journal for
info and warning messages about session closure and hardware state restoration
during these operations.</p>
</section>
<section id="geopm-service-files">
<h2>GEOPM Service Files<a class="headerlink" href="#geopm-service-files" title="Link to this heading"></a></h2>
<p>Beyond the files that come with the installation packages, the GEOPM Service
may generate and modify additional files during its active state. These files
are housed within two primary directories:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">/etc/geopm</span></code>: This directory contains configuration files, including access
control lists. Files here persist across both reboots and service restarts.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">/run/geopm</span></code>: This directory contains files that monitor data about clients
actively engaging the service, files that help maintain the GEOPM Service’s
state, and files that are used by GEOPM’s save/restore mechanism. Should the
service halt unexpectedly, these files aid in its subsequent restart. However,
remember that the <code class="docutils literal notranslate"><span class="pre">/run</span></code> directory’s contents get deleted upon a system reboot.</p></li>
</ul>
<p>Furthermore, the GEOPM Service ensures robust security measures:</p>
<ul class="simple">
<li><p>Both <code class="docutils literal notranslate"><span class="pre">/etc/geopm</span></code> and <code class="docutils literal notranslate"><span class="pre">/run/geopm</span></code> directories and their contained files
are established with restricted access permissions and root ownership.</p></li>
<li><p>The service will avoid reading any file or directory if there’s a relaxation
in access restrictions, non-root ownership, or if they’re substituted by
symbolic links or non-standard files. Should these conditions not be met, the
affected file or directory will be renamed with a UUID and a warning will be
dispatched to the syslog. While these renamed entities can assist an
administrator in investigations, they are otherwise ignored by the GEOPM Service.</p></li>
</ul>
<p>For seamless operation and security, it’s advised to manage the GEOPM Service
system files using GEOPM tools like <code class="docutils literal notranslate"><span class="pre">geopmaccess</span></code>. However, administrators
opting to handle GEOPM system files outside of a GEOPM interface should be
vigilant of the necessary permission and ownership criteria. Delve deeper into
the GEOPM security intricacies by referring to the <a class="reference external" href="security.html">Security Guide</a>.</p>
</section>
<section id="configuring-access-lists">
<h2>Configuring Access Lists<a class="headerlink" href="#configuring-access-lists" title="Link to this heading"></a></h2>
<p>The <a class="reference internal" href="geopmaccess.1.html"><span class="doc">geopmaccess(1)</span></a> command line tool is used
by a system administrator to manage access to the features provided by
the GEOPM Service. The GEOPM Service does not allow read or write
access for any non-root user until the system administrator explicitly
configures the service using the <code class="docutils literal notranslate"><span class="pre">geopmaccess</span></code> command line tool.
This command line interface allows the administrator to set access
permissions for all users, and may extend these default privileges for
specific Unix groups.</p>
</section>
<section id="configuring-systemd-unit-file">
<h2>Configuring Systemd Unit File<a class="headerlink" href="#configuring-systemd-unit-file" title="Link to this heading"></a></h2>
<p>The GEOPM Systemd unit is configured with the <code class="docutils literal notranslate"><span class="pre">geopm.service</span></code> file that is
installed as part of the <code class="docutils literal notranslate"><span class="pre">geopmd</span></code> package. This configuration file may
be amended using the command <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">edit</span> <span class="pre">geopm.service</span></code>. See
<a class="reference external" href="https://man7.org/linux/man-pages/man1/systemctl.1.html">systemctl(1)</a> for
more details.</p>
<p>An administrator may wish to modify the <code class="docutils literal notranslate"><span class="pre">GEOPM_VERBOSITY</span></code> environment variable
set in the configuration file. Increasing this will cause more messages to be
printed in the system journal which may assist in debugging problems where
expected signals or controls are not available.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">GEOPM_VERBOSITY=0</span></code>: Print errors and critical warning messages</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">GEOPM_VERBOSITY=1</span></code>: Print warning messages</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">GEOPM_VERBOSITY=2</span></code>: Print diagnostic info messages</p></li>
</ul>
<p>The scope of messages printed when <code class="docutils literal notranslate"><span class="pre">GEOPM_VERBOSITY</span></code> is non-zero may increase
in the future.</p>
</section>
<section id="the-msr-driver">
<h2>The MSR Driver<a class="headerlink" href="#the-msr-driver" title="Link to this heading"></a></h2>
<p>Access to MSRs enhances the capabilities of the GEOPM Access Service by
providing additional hardware telemetry and controls. While the <strong>GEOPM Access
Service</strong> can function without access to MSRs, it provides a limited set of CPU
features. For the <strong>GEOPM Runtime</strong> to function correctly, these MSR-related
CPU features are necessary. Hence, MSR support is a hard requirement for
the GEOPM Runtime which may be relaxed in a future release.</p>
<p>One of two drivers may be used by the GEOPM Access Service to enable the MSR
features: the standard Linux (in-tree) MSR driver or the msr-safe kernel driver
maintained by LLNL. The msr-safe driver is preferred by GEOPM if both kernel
modules are loaded because it provides low latency interface for reading and
writing many MSR values at once through an <a class="reference external" href="https://man7.org/linux/man-pages/man2/ioctl.2.html">ioctl(2)</a> system call, possibly
improving the performance of GEOPM Runtime or other MSR usages.</p>
<p>The msr-safe kernel driver source code can be found <a class="reference external" href="https://github.com/LLNL/msr-safe">here</a>. It’s distributed with the <a class="reference external" href="https://download.opensuse.org/repositories/hardware/">OpenSUSE
Hardware Repository</a> and
can be installed from the RPMs provided there. For more information about the
necessary configuration of msr-safe see: <a class="reference internal" href="geopmaccess.1.html#configuring-msr-safe"><span class="std std-ref">Configuring msr-safe</span></a> and <a class="reference internal" href="install.html#enable-service"><span class="std std-ref">the install guide</span></a>. Note that subsequent to
v1.7.0 of msr-safe, it is required that the msr-safe allow list be configured
prior to starting the GEOPM Access Service.</p>
<p>In the absence of the msr-safe kernel driver, users may access MSRs using the
standard Linux MSR driver. This can be loaded with the command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>modprobe<span class="w"> </span>msr
</pre></div>
</div>
<p>The standard MSR driver be loaded to enable MSR access through the GEOPM Systemd
Service when msr-safe is not installed.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="spack.html" class="btn btn-neutral float-left" title="Spack Guide" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="security.html" class="btn btn-neutral float-right" title="Security Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2015 - 2025 Intel Corporation. All rights reserved..</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>