autologon_unix.dita@ 99016

Last change on this file since 99016 was 98549, checked in by vboxsync, 2 years ago
Docs: bugref:10302. Uploading .dita user manual files we received from the doc team on 25th Jan.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 8.1 KB

Line
1	<?xml version='1.0' encoding='UTF-8'?>
2	<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
3	<topic xml:lang="en-us" id="autologon_unix">
4	<title>Automated Linux and UNIX Guest Logins</title>
5
6	<body>
7	<p>
8	Oracle VM VirtualBox provides a custom PAM module (Pluggable
9	Authentication Module) which can be used to perform automated
10	guest logins on platforms which support this framework.
11	Virtually all modern Linux and UNIX distributions rely on PAM.
12	</p>
13	<p>
14	For automated logins on Ubuntu, or Ubuntu-derived, distributions
15	using LightDM as the display manager. See
16	<xref href="autologon_unix_lightdm.dita#autologon_unix_lightdm"/>.
17	</p>
18	<p>
19	The <filepath>pam_vbox.so</filepath> module itself
20	<i>does not</i> do an actual verification of the
21	credentials passed to the guest OS. Instead it relies on other
22	modules such as <filepath>pam_unix.so</filepath> or
23	<filepath>pam_unix2.so</filepath> down in the PAM stack to do
24	the actual validation using the credentials retrieved by
25	<filepath>pam_vbox.so</filepath>. Therefore
26	<filepath>pam_vbox.so</filepath> has to be on top of the
27	authentication PAM service list.
28	</p>
29	<note>
30	<p>
31	The <filepath>pam_vbox.so</filepath> module only supports the
32	<codeph>auth</codeph> primitive. Other primitives such as
33	<codeph>account</codeph>, <codeph>session</codeph>, or
34	<codeph>password</codeph> are not supported.
35	</p>
36	</note>
37	<p>
38	The <filepath>pam_vbox.so</filepath> module is shipped as part
39	of the Guest Additions but it is not installed and/or activated
40	on the guest OS by default. In order to install it, it has to be
41	copied from
42	<filepath>/opt/VBoxGuestAdditions-<varname>version</varname>/other/</filepath>
43	to the security modules directory. This is usually
44	<filepath>/lib/security/</filepath> on 32-bit Linux guests or
45	<filepath>/lib64/security/</filepath> on 64-bit Linux guests.
46	Please refer to your guest OS documentation for the correct PAM
47	module directory.
48	</p>
49	<p>
50	For example, to use <filepath>pam_vbox.so</filepath> with a
51	Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log
52	in users automatically with the credentials passed by the host,
53	configure the guest OS as follows:
54	</p>
55	<ol>
56	<li>
57	<p>
58	Copy the <filepath>pam_vbox.so</filepath> module to the
59	security modules directory. In this case,
60	<filepath>/lib/security</filepath>.
61	</p>
62	</li>
63	<li>
64	<p>
65	Edit the PAM configuration file for GDM, found at
66	<filepath>/etc/pam.d/gdm</filepath>. Add the line
67	<codeph>auth requisite pam_vbox.so</codeph> at the top.
68	Additionally, in most Linux distributions there is a file
69	called <filepath>/etc/pam.d/common-auth</filepath>. This
70	file is included in many other services, like the GDM file
71	mentioned above. There you also have to add the line
72	<codeph>auth requisite pam_vbox.so</codeph>.
73	</p>
74	</li>
75	<li>
76	<p>
77	If authentication against the shadow database using
78	<filepath>pam_unix.so</filepath> or
79	<filepath>pam_unix2.so</filepath> is desired, the argument
80	<codeph>try_first_pass</codeph> for
81	<filepath>pam_unix.so</filepath> or
82	<codeph>use_first_pass</codeph> for
83	<filepath>pam_unix2.so</filepath> is needed in order to pass
84	the credentials from the Oracle VM VirtualBox module to the shadow
85	database authentication module. For Ubuntu, this needs to be
86	added to <filepath>/etc/pam.d/common-auth</filepath>, to the
87	end of the line referencing
88	<filepath>pam_unix.so</filepath>. This argument tells the
89	PAM module to use credentials already present in the stack,
90	such as the ones provided by the Oracle VM VirtualBox PAM module.
91	</p>
92	</li>
93	</ol>
94	<note type="attention">
95	<p>
96	An incorrectly configured PAM stack can effectively prevent
97	you from logging into your guest system.
98	</p>
99	</note>
100	<p>
101	To make deployment easier, you can pass the argument
102	<codeph>debug</codeph> right after the
103	<filepath>pam_vbox.so</filepath> statement. Debug log output
104	will then be recorded using syslog.
105	</p>
106	<note>
107	<p>
108	By default, <userinput>pam_vbox</userinput> does not wait for
109	credentials to arrive from the host. When a login prompt is
110	shown, for example by GDM/KDM or the text console, and
111	<userinput>pam_vbox</userinput> does not yet have credentials it
112	does not wait until they arrive. Instead the next module in
113	the PAM stack, depending on the PAM configuration, will have
114	the chance for authentication.
115	</p>
116	</note>
117	<p><userinput>pam_vbox</userinput> supports various guest property
118	parameters that are located in
119	<filepath>/VirtualBox/GuestAdd/PAM/</filepath>. These parameters
120	allow <userinput>pam_vbox</userinput> to wait for credentials to be
121	provided by the host and optionally can show a message while
122	waiting for those. The following guest properties can be set:
123	</p>
124	<ul>
125	<li>
126	<p><codeph>CredsWait</codeph>: Set to 1 if
127	<userinput>pam_vbox</userinput> should start waiting until
128	credentials arrive from the host. Until then no other
129	authentication methods such as manually logging in will be
130	available. If this property is empty or gets deleted no
131	waiting for credentials will be performed and
132	<userinput>pam_vbox</userinput> will act like before. This
133	property must be set read-only for the guest
134	(<codeph>RDONLYGUEST</codeph>).
135	</p>
136	</li>
137	<li>
138	<p><codeph>CredsWaitAbort</codeph>: Aborts waiting for
139	credentials when set to any value. Can be set from host and
140	the guest.
141	</p>
142	</li>
143	<li>
144	<p><codeph>CredsWaitTimeout</codeph>: Timeout, in seconds, to
145	let <userinput>pam_vbox</userinput> wait for credentials to
146	arrive. When no credentials arrive within this timeout,
147	authentication of <userinput>pam_vbox</userinput> will be set to
148	failed and the next PAM module in chain will be asked. If
149	this property is not specified, set to 0 or an invalid
150	value, an infinite timeout will be used. This property must
151	be set read-only for the guest
152	(<codeph>RDONLYGUEST</codeph>).
153	</p>
154	</li>
155	</ul>
156	<p>
157	To customize <userinput>pam_vbox</userinput> further there are the
158	following guest properties:
159	</p>
160	<ul>
161	<li>
162	<p><codeph>CredsMsgWaiting</codeph>: Custom message showed
163	while pam_vbox is waiting for credentials from the host.
164	This property must be set read-only for the guest
165	(<codeph>RDONLYGUEST</codeph>).
166	</p>
167	</li>
168	<li>
169	<p><codeph>CredsMsgWaitTimeout</codeph>: Custom message
170	showed when waiting for credentials by
171	<userinput>pam_vbox</userinput> has timed out. For example, they
172	did not arrive within time. This property must be set
173	read-only for the guest (<codeph>RDONLYGUEST</codeph>).
174	</p>
175	</li>
176	</ul>
177	<note>
178	<p>
179	If a <userinput>pam_vbox</userinput> guest property does not have
180	the correct flag set (<codeph>RDONLYGUEST</codeph>) the
181	property is ignored and, depending on the property, a default
182	value will be used. This can result in pam_vbox not waiting
183	for credentials. Consult the appropriate syslog file for more
184	information and use the <codeph>debug</codeph> option.
185	</p>
186	</note>
187	</body>
188	</topic>

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format