VirtualBox

source: vbox/trunk/doc/manual/en_US/dita/topics/autologon_unix.dita@ 105499

Last change on this file since 105499 was 105499, checked in by vboxsync, 4 months ago

Docs: ​More whitespace fixes.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.6 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><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>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette