forked from fleet-commander/fleet-commander.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocumentation.html
More file actions
376 lines (376 loc) · 17.1 KB
/
documentation.html
File metadata and controls
376 lines (376 loc) · 17.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
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
<!DOCTYPE html>
<html>
<head>
<title>
Fleet Commander
</title>
<meta content='text/html; charset=UTF8' http-equiv='content-type'>
<meta content='Manage your large GNOME deployments with ease.' name='description'>
<meta content='fleet,commander,fleetcommander' name='keywords'>
<meta content='width=device-width,initial-scale=1' name='viewport'>
<link href='img/favicon-4b8b19c3.png' rel='icon' type='image/png'>
<link href='favicon.ico' rel='shortcut icon' type='image/x-icon'>
<link href='img/favicon57-7d2e27eb.png' rel='apple-touch-icon' sizes='57x57'>
<link href='img/favicon152-c156af3a.png' rel='apple-touch-icon' sizes='152x152'>
<link href="stylesheets/fonts-6c582ae6.css" rel="stylesheet" />
<link href="stylesheets/site-5f74a37f.css" rel="stylesheet" />
<link href="stylesheets/animate-0a10c6dd.css" rel="stylesheet" />
</head>
<body id='page-top'>
<nav class='navbar navbar-default navbar-fixed-top' id='mainNav'>
<div class='container-fluid'>
<!-- Brand and toggle get grouped for better mobile display -->
<div class='navbar-header'>
<button class='navbar-toggle collapsed' data-target='#bs-example-navbar-collapse-1' data-toggle='collapse' type='button'>
<span class='sr-only'>Toggle navigation</span>
<span class='icon-bar'></span>
<span class='icon-bar'></span>
<span class='icon-bar'></span>
</button>
<a class="navbar-brand page-scroll" href="./">Fleet Commander</a>
</div>
<div class='collapse navbar-collapse' id='bs-example-navbar-collapse-1'>
<ul class='nav navbar-nav navbar-right'>
<li>
<a href='/index.html#about'>About</a>
</li>
<li>
<a href='/index.html#getting'>Getting Fleet Commander</a>
</li>
<li>
<a class="page-scroll" href="documentation.html">Documentation</a>
</li>
<li>
<a href='/index.html#get-involved'>Get Involved</a>
</li>
</ul>
<!-- /.navbar-collapse -->
</div>
</div>
<!-- /.container-fluid -->
</nav>
</body>
<section id='documentation'>
<div class='container'>
<div class='row'>
<div class='col-lg-10 col-lg-offset-1'>
<h1 class='section-heading text-center'>Overview</h1>
<hr class='primary'>
<p>
Fleet Commander is an application that allows you to manage the desktop configuration of a large network of users and workstations/laptops. It is primarily targeted to Linux systems based on the GNOME desktop.
</p>
<p>
Fleet Commander consists of three components:
<ul>
<li>
a FreeIPA plugin that allows to store profiles into your domain controller,
</li>
<li>
a Cockpit plugin that serves the administration, interface
</li>
<li>
a client side service that runs on every host of the network.
</li>
</ul>
</p>
<p>
Fleet Commander uses libvirt and KVM to run a virtual desktop session that allows the user to live edit the configuration of the applications on a template system that resembles the client setup.
</p>
</div>
</div>
</div>
<div class='container'>
<div class='row'>
<div class='col-lg-10 col-lg-offset-1'>
<h1 class='section-heading text-center'>FreeIPA Plugin</h1>
<hr class='primary'>
<p>
In order to use Fleet Commander, you need an operative FreeIPA domain server. For more information on how to prepare a FreeIPA environment to use Fleet Commander, please refer to FreeIPA quick start guide
</p>
<p>
Once you have a FreeIPA environment working, you need to install the FreeIPA desktop profiles plugin on your domain server. In fedora, you can run the following command:
</p>
<pre>$ sudo dnf install freeipa-desktop-profile</pre>
<p>
After installing the package you should be able to check the plugin by running the following commands in a domain enrolled machine:
</p>
<pre>$ kinit admin
Password for admin@FC.IPA:
$ ipa deskprofileconfig-show
Priority of profile application: 1</pre>
</div>
</div>
</div>
<div class='container'>
<div class='row'>
<div class='col-lg-10 col-lg-offset-1'>
<h1 class='section-heading text-center'>Admin</h1>
<hr class='primary'>
<h2>Installation</h2>
<p>
Fleet commander admin is a Cockpit plugin, so you will need to follow these instructions to install Cockpit.
</p>
<p>
Make sure that cockpit is up and running. You can check it by pointing your browser to http://localhost:9090.
</p>
<p>
If it is not working you can try this:
</p>
<pre>$ sudo systemctl start cockpit</pre>
<p>
At this point, you should be able to access the cockpit interface in your browser.
</p>
<p>
<img src="img/screenshots/01_cockpit_login_screen-b35139fe.png" />
</p>
<p>
Next step is to install fleet-commander-admin package:
</p>
<pre>$ sudo dnf install fleet-commander-admin</pre>
<h2>Usage</h2>
<h3>Starting out</h3>
<p>
We will assume that you have the cockpit service running and can access the Cockpit login page. If you need more information about setting up cockpit you can refer to http://cockpit-project.org/running.html cockpit documentation
</p>
<p>
Login with domain credentials for a user with administrative access or with access to desktop profiles management. Otherwise, you will not be able to use Fleet Commander Admin.
</p>
<p>
Click on the Fleet Commander option at cockpit sidebar, and you will see Fleet Commander loading screen.
</p>
<p>
<img src="img/screenshots/02_fc_loading_screen-ecb820e0.png" />
</p>
<p>
The first time you use Fleet Commander, you will need to wait a few seconds to allow Fleet Commander Admin to set up the environment for the application. Please be patient.
</p>
<h3>Configure Fleet Commander</h3>
<p>
If this is the first time you’re using Fleet Commander you will be prompted to configure the global policy and libvirt host information for Fleet Commander.
</p>
<p>
<img src="img/screenshots/03_fc_settings-59c0cfc2.png" />
</p>
<p>
You can access the settings using the Settings button.
</p>
<h4>Global policy</h4>
<p>
Fleet Commander allows you to setup a global policy for determining how to apply multiple profiles to same user / group / host / hostgroup.
</p>
<p>
In the selection box labeled Global policy you can select the precedence policy. The Default is User-Group-Host-Hostgroup, but you can change it to fit your needs.
</p>
<h4>Libvirt host</h4>
<p>
The Live session functionality of Fleet commander requires a working ssh connection to a libvirt host.
</p>
<p>
Click on the Settings button and fill in the appropriate input fields:
</p>
<p>
Fleet Commander virtual environment host - the hostname/ip of the libvirt host.
</p>
<ul>
<li>
Username for connection - Name of the user on the libvirt host.
</li>
<li>
Libvirt mode - system or session. If you created the VMs using GNOME Boxes or the user does not have privileges, you will probably want to use the session mode.
</li>
<li>
If you're using GNOME Boxes on the same host where cockpit and the Fleet Commander interface is running you will likely want to use localhost as the host, your own username as username and Session as Libvirt mode.
</li>
</ul>
<p>
Fleet commander generates its own public key, which needs to be added to .ssh/authorized_keys for the appropriate user on the libvirt host.
</p>
<p>
The easier way to do that is to click on the Install public key button to install the public key. Fleet Commander will ask you for the user's password. Password will be only used for key installation and will not be stored anywhere.
</p>
<p>
Don't forget to start sshd on the libvirt host, otherwise, Fleet commander won't be able to connect.
</p>
<p>
If, for some reason, Fleet commander is unable to install the public key on the host, you can do it manually by clicking on the show button next to "Public key" and copying it to .ssh/authorized_hosts for the appropriate user on the host.
</p>
<p>
You should now be ready to use live sessions to edit profiles.
</p>
<h3>Managing profiles</h3>
<p>
After configuring Fleet Commander you will be able to create and manage your profiles.
</p>
<p>
You can add and remove profiles using the `Add Profile` button.
</p>
<p>
The screenshot below shows the profile list that contains all profiles you have created. Profiles can be edited or removed using the `Edit` and `Remove` buttons.
</p>
<p>
<img src="img/screenshots/04_fc_main_screen-f3e6bcb3.png" />
</p>
<p>
When you add or edit a profile, this is the information you can set up:
</p>
<ul>
<li>
Name: name of the profile
</li>
<li>
Description: description of the profile
</li>
<li>
Priority: priority of the profile (used to determine profile precedence)
</li>
<li>
Users: users you want the profile to apply to
</li>
<li>
Groups: same as Users, but for groups
</li>
<li>
Hosts: hosts this profile will apply to.
</li>
<li>
Host Groups: same as Hosts, but for groups of hosts
</li>
</ul>
<p>
If you do not select any host or hostgroup for your profile, it will apply to every host in your domain.
</p>
<p>
<img src="img/screenshots/05_editing_profile-e20b935b.png" />
</p>
<h3>Using live sessions</h3>
<p>
We will assume you have a working virtual environment host set up. If not, see [[#configure_libvirt_host|Configure libvirt host]]
</p>
<p>
When editing a profile, simply click on the `Live session` button. You will get a list of available VMs you can use as a template. If you don't see any VMs, you may need to add some - see [[#managing_template_vms|Managing template VMs]].
</p>
<p>
<img src="img/screenshots/06_virtual_machines_list-5556559f.png" />
</p>
<p>
Clicking a VM will launch a volatile clone of it. Since the clone is volatile, all changes to the VM will be discarded on shutdown, meaning you can experiment without the fear of messing up the template VM.
</p>
<p>
After you've made some changes, click on the `Review and submit` button and select the changes you want to add to the profile.
</p>
<p>
<img src="img/screenshots/07_live_session_change_review-94862769.png" />
</p>
<h3>Managing Template VMs</h3>
<p>
Fleet commander is tested and supported on Fedora, but you should be able to use any distribution. Setting up new template VMs is really simple, you just need to create a VM inside a libvirt/KVM hypervisor. For example, you can use GNOME Boxes.
</p>
<p>
In order to "report changes back" to Fleet commander, the VM itself must run Fleet Commander Logger. Start the VM and install fleet-commander-logger:
</p>
<pre>$ sudo dnf install fleet-commander-logger</pre>
<p>
Logger will automatically start after logging in, so there’s no need to enable it manually. When it starts it will check that a special device file is available in /dev/virtio-ports/, and if it does not exist, logger will not record any changes and simply quit as soon as it's started. That device file is created automatically by Fleet Commander when you start the template VM from Fleet Commander Admin interface.
</p>
<p>
Note that while it's technically possible to install logger directly inside a Fleet commander live session, your changes would be destroyed every time your turn off the VM.
</p>
</div>
</div>
</div>
<div class='container'>
<div class='row'>
<div class='col-lg-10 col-lg-offset-1'>
<h1 class='section-heading text-center'>Client</h1>
<hr class='primary'>
<p>
Fleet Commander Client is in charge of applying the changes from your profiles to the machines in your network.
</p>
<p>
To install it just execute the following command:
</p>
<pre>$ sudo dnf install fleet-commander-client</pre>
<p>
After installation it will be executed automatically when you login in a domain with Fleet Commander support, and will setup any configuration that applies to your user.
</p>
</div>
</div>
</div>
<div class='container'>
<div class='row'>
<div class='col-lg-10 col-lg-offset-1'>
<h1 class='text-center'>Troubleshooting admin problems</h1>
<hr class='primary'>
<p>Before starting any troubleshooting with fleet commander, we strongly recommend you to add log_level = debug option to /etc/xdg/fleet-commander-admin.conf under [admin] section so you can use journalctl to see more verbose output.</p>
<h2>"Error connecting to FreeIPA"</h2>
<ul></ul>
<li>
Make sure the machine where you are running Fleet Commander Admin is enrolled in the domain.
</li>
<li>
Check you are able to obtain a Kerberos ticket from your FreeIPA domain.
</li>
<li>
Check the user you're using have administrative access to FreeIPA domain.
</li>
<h2>"Error getting domain list"</h2>
<ul></ul>
<li>
Make sure sshd is running on the virtual environment host.
</li>
<li>
Set chmod 600 or 700 to .ssh/authorized_keys on the libvirt host.
</li>
<li>
Try logging in through SSH manually with verbose enabled.
</li>
</div>
</div>
</div>
</section>
<section class='bg-black' id='footer'>
<div class='container'>
<div class='row'>
<div class='col-lg-3 col-lg-offset-1'>
<a class='navbar-brand page-scroll' href='#page-top'>
<img title="FleetCommander" class="full" src="img/logo-0d69f283.svg" />
</a>
</div>
<ul class='col-lg-7'>
<li class='toplevel'>
<a href="./">Home</a>
</li>
<li class='toplevel'>
<!-- id links on index page -->
<a class='page-scroll' href='/index.html#about'>About</a>
</li>
<li class='toplevel'>
<!-- id links on index page -->
<a class='page-scroll' href='/index.html#getting'>Getting Fleet Commander</a>
</li>
<li class='toplevel'>
<!-- id links on index page -->
<a class="page-scroll" href="documentation.html">Documentation</a>
</li>
<li class='toplevel'>
<!-- id links on index page -->
<a class='page-scroll' href='/index.html#get-involved'>Get Involved</a>
</li>
</ul>
</div>
</div>
</section>
<script src="javascripts/jquery-1797d73e.js"></script>
<script src="javascripts/jquery.easing.min-603599b4.js"></script>
<script src="javascripts/jquery.toc.min-265bae56.js"></script>
<script src="javascripts/bootstrap-8cf4186c.js"></script>
<script src="javascripts/all-cebf4876.js"></script>
<script type="text/javascript">
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-68811788-2', 'auto');
ga('send', 'pageview');
</script>
</html>