autologon_unix.dita@ 105293

Last change on this file since 105293 was 105176, checked in by vboxsync, 7 months ago
Docs: bugref:10705. Merging some more changes from docs team's dita topic files. not complete.
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	<ph conkeyref="vbox-conkeyref-phrases/product-name"/> 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> The <filepath>pam_vbox.so</filepath> module is shipped as part of the Guest Additions but it
38	is not installed or activated on the guest OS by default. In order to install it, it has to be
39	copied from <filepath>/opt/VBoxGuestAdditions-<varname>version</varname>/other/</filepath> to
40	the security modules directory. This is usually <filepath>/lib/security/</filepath> on 32-bit
41	Linux guests or <filepath>/lib64/security/</filepath> on 64-bit Linux guests. Please refer to
42	your guest OS documentation for the correct PAM module directory. </p>
43	<p>
44	For example, to use <filepath>pam_vbox.so</filepath> with a
45	Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log
46	in users automatically with the credentials passed by the host,
47	configure the guest OS as follows:
48	</p>
49	<ol>
50	<li>
51	<p>
52	Copy the <filepath>pam_vbox.so</filepath> module to the
53	security modules directory. In this case,
54	<filepath>/lib/security</filepath>.
55	</p>
56	</li>
57	<li>
58	<p>
59	Edit the PAM configuration file for GDM, found at
60	<filepath>/etc/pam.d/gdm</filepath>. Add the line
61	<codeph>auth requisite pam_vbox.so</codeph> at the top.
62	Additionally, in most Linux distributions there is a file
63	called <filepath>/etc/pam.d/common-auth</filepath>. This
64	file is included in many other services, like the GDM file
65	mentioned above. There you also have to add the line
66	<codeph>auth requisite pam_vbox.so</codeph>.
67	</p>
68	</li>
69	<li>
70	<p> If authentication against the shadow database using <filepath>pam_unix.so</filepath> or
71	<filepath>pam_unix2.so</filepath> is required, the argument
72	<codeph>try_first_pass</codeph> for <filepath>pam_unix.so</filepath> or
73	<codeph>use_first_pass</codeph> for <filepath>pam_unix2.so</filepath> is needed in order
74	to pass the credentials from the <ph conkeyref="vbox-conkeyref-phrases/product-name"/>
75	module to the shadow database authentication module. For Ubuntu, this must be added to
76	<filepath>/etc/pam.d/common-auth</filepath>, to the end of the line referencing
77	<filepath>pam_unix.so</filepath>. This argument tells the PAM module to use credentials
78	already present in the stack, such as the ones provided by the <ph
79	conkeyref="vbox-conkeyref-phrases/product-name"/> PAM module. </p>
80	</li>
81	</ol>
82	<note type="caution">
83	<p>
84	An incorrectly configured PAM stack can effectively prevent
85	you from logging into your guest system.
86	</p>
87	</note>
88	<p>
89	To make deployment easier, you can pass the argument
90	<codeph>debug</codeph> right after the
91	<filepath>pam_vbox.so</filepath> statement. Debug log output
92	will then be recorded using syslog.
93	</p>
94	<note>
95	<p>
96	By default, <userinput>pam_vbox</userinput> does not wait for
97	credentials to arrive from the host. When a login prompt is
98	shown, for example by GDM/KDM or the text console, and
99	<userinput>pam_vbox</userinput> does not yet have credentials it
100	does not wait until they arrive. Instead the next module in
101	the PAM stack, depending on the PAM configuration, will have
102	the chance for authentication.
103	</p>
104	</note>
105	<p><userinput>pam_vbox</userinput> supports various guest property
106	parameters that are located in
107	<filepath>/VirtualBox/GuestAdd/PAM/</filepath>. These parameters
108	allow <userinput>pam_vbox</userinput> to wait for credentials to be
109	provided by the host and optionally can show a message while
110	waiting for those. The following guest properties can be set:
111	</p>
112	<ul>
113	<li>
114	<p><codeph>CredsWait</codeph>: Set to 1 if
115	<userinput>pam_vbox</userinput> should start waiting until
116	credentials arrive from the host. Until then no other
117	authentication methods such as manually logging in will be
118	available. If this property is empty or gets deleted no
119	waiting for credentials will be performed and
120	<userinput>pam_vbox</userinput> will act like before. This
121	property must be set read-only for the guest
122	(<codeph>RDONLYGUEST</codeph>).
123	</p>
124	</li>
125	<li>
126	<p><codeph>CredsWaitAbort</codeph>: Aborts waiting for
127	credentials when set to any value. Can be set from host and
128	the guest.
129	</p>
130	</li>
131	<li>
132	<p><codeph>CredsWaitTimeout</codeph>: Timeout, in seconds, to
133	let <userinput>pam_vbox</userinput> wait for credentials to
134	arrive. When no credentials arrive within this timeout,
135	authentication of <userinput>pam_vbox</userinput> will be set to
136	failed and the next PAM module in chain will be asked. If
137	this property is not specified, set to 0 or an invalid
138	value, an infinite timeout will be used. This property must
139	be set read-only for the guest
140	(<codeph>RDONLYGUEST</codeph>).
141	</p>
142	</li>
143	</ul>
144	<p>
145	To customize <userinput>pam_vbox</userinput> further there are the
146	following guest properties:
147	</p>
148	<ul>
149	<li>
150	<p><codeph>CredsMsgWaiting</codeph>: Custom message showed
151	while pam_vbox is waiting for credentials from the host.
152	This property must be set read-only for the guest
153	(<codeph>RDONLYGUEST</codeph>).
154	</p>
155	</li>
156	<li>
157	<p><codeph>CredsMsgWaitTimeout</codeph>: Custom message
158	showed when waiting for credentials by
159	<userinput>pam_vbox</userinput> has timed out. For example, they
160	did not arrive within time. This property must be set
161	read-only for the guest (<codeph>RDONLYGUEST</codeph>).
162	</p>
163	</li>
164	</ul>
165	<note>
166	<p>
167	If a <userinput>pam_vbox</userinput> guest property does not have
168	the correct flag set (<codeph>RDONLYGUEST</codeph>) the
169	property is ignored and, depending on the property, a default
170	value will be used. This can result in pam_vbox not waiting
171	for credentials. Consult the appropriate syslog file for more
172	information and use the <codeph>debug</codeph> option.
173	</p>
174	</note>
175	</body>
176	</topic>

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

Download in other formats:

Original Format