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