1 Introduction
2 ------------
3
4 The userinstall distribution consists of a number of scripts, together with a
5 short configuration file, which allows non-root users to set up and use their
6 own package and dependency management facilities and to download and install
7 Debian packages without having to obtain root privileges. The software within
8 installed packages may then be used, subject to certain constraints such as
9 program environments, library paths, and so on. In effect, userinstall
10 provides a personal package manager.
11
12 In addition, userinstall also provides tools to manage conventional chroot
13 filesystem areas and User Mode Linux system images. Such capabilities are
14 useful when needing to run distributions that are sufficiently different from
15 the host system's distribution that the non-root approach no longer works,
16 due to system library or kernel incompatibilities.
17
18 The following table summarises the capabilities and limitations of the
19 different modes of the software:
20
21 Programs Unprivileged usage Same distribution Other versions
22 -------- ------------------ ----------------- --------------
23
24 user-* Yes Yes Probably not
25 (sensitive to core
26 library versions)
27
28 user-* No Yes Yes (subject to
29 (with --root option) kernel suitability)
30
31 uml-* Yes (although Yes Yes
32 networking must be
33 set up by root)
34
35 Contact, Copyright and Licence Information
36 ------------------------------------------
37
38 The current Web page for userinstall at the time of release is:
39
40 http://www.boddie.org.uk/paul/userinstall.html
41
42 Copyright and licence information can be found in the docs directory - see
43 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
44
45 Thanks to Piotr Roszatycki, the maintainer of fakechroot, for helpfully fixing
46 system call coverage in that utility in order to attempt to support
47 cross-distribution bootstrapping.
48
49 Dependencies
50 ------------
51
52 fakeroot Tested with 1.5.10ubuntu2
53 fakechroot 2.8 or later required
54 debootstrap Tested with 0.3.3.2ubuntu3 on Ubuntu Hoary 5.04, 1.0.7~feisty1
55 on Ubuntu Feisty 7.04, 1.0.20~hardy1 on Ubuntu Hardy
56 lsb-release Tested with 3.2-23.2squeeze1 (apparently required for Debian
57 squeeze and subsequent distribution versions)
58
59 New in userinstall 0.2.1 (Changes since userinstall 0.2)
60 --------------------------------------------------------
61
62 * Added more User Mode Linux and configuration-related documentation.
63 * Introduced usage of the lsb_release command in preference to the
64 /etc/lsb-release file.
65
66 New in userinstall 0.2 (Changes since userinstall 0.1)
67 ------------------------------------------------------
68
69 * Adopted lsb-release environment variables instead of new ones like
70 DISTNAME, exposing derivatives of these variables by default.
71 * Added explicit keyring package installation.
72 * Added -do scripts for configuring and entering the chroot.
73 * Removed specific apt- and dpkg-related scripts, replacing them with the
74 general -do scripts.
75 * Added --root options to certain scripts in order to support normal chroot
76 installations. Added --dev option for bind mounting of /dev in normal
77 chroot installations.
78 * Added support for UML instance construction from distribution
79 installations, along with networking support and a uml-net script. Also
80 added some support for booting from initrd files and installation media
81 image files.
82
83 Configuration
84 -------------
85
86 If the system defaults are not to be used, or if userinstall is not installed
87 as a system package, the userinstall-defaults file supplied with the
88 distribution may be edited to specify the nature and location of the personal
89 package manager.
90
91 The following settings can be edited:
92
93 USERINSTALL_ID This should reflect the distribution being used or, in
94 special cases, a different distribution. Examples
95 include Debian and Ubuntu.
96
97 USERINSTALL_CODENAME This should reflect the version of the distribution
98 being used and need only be altered in special
99 situations (such as the creation of a sandbox for
100 testing other distributions).
101
102 Examples of codenames include hardy and jaunty for
103 Ubuntu and lenny and squeeze for Debian. Note that the
104 setup process may not work with different distributions
105 due to library incompatibilities.
106
107 PACKAGEROOT The location of the personal package manager in the
108 filesystem.
109
110 See the /etc/lsb-release file for example values describing your own system,
111 with the DISTRIB prefix used instead of the USERINSTALL prefix for each of the
112 settings.
113
114 If a completely new userinstall-defaults file is created, it is essential that
115 the above variables be defined so that the scripts know where to create or to
116 find the personal package manager. Typically, a new userinstall-defaults file
117 will reside in the current directory when the different userinstall commands
118 are being issued.
119
120 Creating a Personal Package Manager
121 -----------------------------------
122
123 In order to install packages as a non-root user, first invoke the user-setup
124 script; this will create and initialise a basic Debian system with a basic set
125 of packages installed. For example, with userinstall installed as a system
126 package, using the system defaults:
127
128 user-setup
129
130 It is possible to override the "template" for the system by specifying a
131 "mirror" location. This is useful if you have the CD or DVD image for the
132 distribution already mounted in the filesystem. For example:
133
134 user-setup file:///cdrom
135
136 sudo mount -o loop /home/me/downloads/kubuntu-7.04-alternate-i386.iso /tmp/cdrom
137 user-setup file:///tmp/cdrom
138
139 A URL must be specified as the "mirror" location, not a normal filename.
140
141 Once the installation is complete, some post-installation is necessary:
142
143 user-postsetup
144
145 If a different distribution is being used for the package manager than that
146 being run on the system, it might be necessary to specify a country code so
147 that the configuration of package repositories can be performed successfully.
148 For example, for repositories mirrored in the United Kingdom (UK):
149
150 user-postsetup uk
151
152 At this point, the package manager should be ready to use.
153
154 Adding Package Repositories to the Package Manager
155 --------------------------------------------------
156
157 To get access to repositories of packages beyond those provided by the basic
158 distribution, edit the /etc/apt/sources.list file inside the system. The
159 user-path script can help you find the exact location of the file:
160
161 user-path /etc/apt/sources.list
162
163 And you can edit the file directly with a text editor (such as vi) as follows:
164
165 vi `user-path /etc/apt/sources.list`
166
167 Installing Packages
168 -------------------
169
170 To install packages from other repositories, invoke the user-do script and
171 specify the apt-get program together with options expected by that program.
172 For example:
173
174 user-do apt-get --help
175 user-do apt-get update
176
177 Packages can then be installed. For example:
178
179 user-do apt-get install python-cmdsyntax
180
181 Provided that the specified packages are known and their dependencies can be
182 met, they will be installed into the system.
183
184 Installing Single Packages
185 --------------------------
186
187 To install individual package files, first copy them into the package manager
188 directory hierarchy. For example:
189
190 cp python-cmdsyntax_0.91-0ubuntu2_all.deb `user-path /tmp`
191
192 The invoke the dpkg program through the user-do script as follows:
193
194 user-do dpkg -i /tmp/python-cmdsyntax_0.91-0ubuntu2_all.deb
195
196 Using Packages
197 --------------
198
199 Unlike most packages installed in the usual way by the root user, the installed
200 packages will not reside within a directory hierarchy rooted at / - the top of
201 the filesystem. Instead, they will reside in a location such as the following:
202
203 /home/me/.userinstall
204 /tmp/packages
205
206 (The precise location may be found by running the user-path script.)
207
208 Consequently, to make use of the installed software, it may be necessary to
209 edit your environment in a number of ways so that it may be located and
210 correctly loaded, initialised and executed.
211
212 Using Python Packages
213 ---------------------
214
215 Installed Python packages may be made available to Python by defining the
216 PYTHONPATH to include the directories usually searched by Python, but which
217 are actually located within the personal package management environment. For
218 example, with the Python 2.5 site-packages directory:
219
220 PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5
221
222 More complicated extension modules may require further adjustments to the
223 LD_LIBRARY_PATH and PYTHONPATH variables:
224
225 export LD_LIBRARY_PATH=`user-path /usr/lib`
226 export PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/`
227 export PYTHONPATH=${PYTHONPATH}:`user-path /var/lib/python-support/python2.5`
228
229 Entering the Package Manager
230 ----------------------------
231
232 It is also possible to administer the package manager from within the
233 installation:
234
235 user-do
236
237 This should provide a "root" prompt which can then be used to issue commands
238 within the package manager environment. For example:
239
240 apt-get update && apt-get upgrade
241
242 Creating and Entering a Package Manager in Root Mode
243 ----------------------------------------------------
244
245 The user-setup, user-postsetup and user-do scripts also support a --root
246 option which sets up a package manager for a user with root privileges. To
247 set up such an installation, the following commands can be used:
248
249 user-setup --root
250 user-postsetup --root
251
252 Entering the installation is done using the user-do script:
253
254 user-do --root
255
256 Note that in root mode, the /proc and /sys filesystems are mounted within the
257 installation. Care must be taken not to delete the contents of these
258 directories within the installation while the above command is running;
259 otherwise, this can potentially damage the main operating system installation
260 on your computer.
261
262 Using the Host's Device Filesystem
263 ----------------------------------
264
265 In root mode, the /dev filesystem on the host can be mounted by using the
266 --dev option with user-do:
267
268 user-do --root --dev
269
270 Note that care must be taken not to delete the contents of this directory
271 within the installation while the above command is running.
272
273 Enabling Audio in Root Mode
274 ---------------------------
275
276 Together with the --root and --dev options, audio can be enabled for
277 applications within an installation by adding users to the audio group in
278 /etc/group. In addition, it may be necessary to run an audio manager daemon
279 depending on the system used to manage the audio on the host.
280
281 For example, the artsd package may need installing in order to make the
282 corresponding artsdsp program available to applications within the package
283 manager.
284
285 Configuration of User Mode Linux Instances
286 ------------------------------------------
287
288 For some applications, it can be desirable to provide a completely isolated
289 environment for package installation and testing. This can be performed using
290 the User Mode Linux (UML) software.
291
292 Alongside the userinstall-defaults file, a userinstall-defaults-uml file must
293 be made available. As with the generic userinstall-defaults file, the
294 UML-specific configuration in userinstall-defaults-uml must be edited to
295 reflect the desired settings such that appropriate network addresses are used
296 along with a suitable Linux kernel.
297
298 Constructing UML Instances
299 --------------------------
300
301 Since UML needs to see its filesystems as images, not directories within an
302 existing filesystem, the uml-make-image script needs to create these image
303 files. For example, to create a root filesystem 4GB in size, along with a swap
304 file 512MB in size:
305
306 uml-make-image 4 512
307
308 This will create a UML instance from an existing package manager installation.
309 However, if a UML instance will be populated using installation media
310 (described below), the following is more suitable:
311
312 uml-make-image --no-fs 4 512
313
314 This does not create filesystems but instead leaves it to the installer to
315 partition the files created.
316
317 Building User Mode Linux
318 ------------------------
319
320 To make a User Mode Linux executable, run the uml-build-linux script.
321
322 Enabling Networking for UML Instances
323 -------------------------------------
324
325 To enable networking for a UML instance, use the uml-net script:
326
327 sudo uml-net --start $USER
328
329 Here, $USER should be expanded to the name of the user running the above
330 command, not the root user.
331
332 To stop networking, use the same script:
333
334 sudo uml-net --stop
335
336 Entering or Starting UML Instances
337 ----------------------------------
338
339 To enter a UML instance, use the uml-do script, specifying an amount of memory
340 to allocate to the instance:
341
342 uml-do 512M
343
344 Specifying the --net option allows networking to be used by the instance, if
345 set up as described above:
346
347 uml-do 512M --net
348
349 Accessing UML Consoles
350 ----------------------
351
352 During the boot process, User Mode Linux should report a number of lines of
353 the following form:
354
355 Virtual console 1 assigned device '/dev/pts/3'
356
357 This indicates that to access console 1, the given device should be accessed.
358 This can be done using the screen command as follows:
359
360 screen /dev/pts/3
361
362 You may need to press Return/Enter to "wake up" the console in order to see a
363 login prompt.
364
365 Booting into UML from Installation Media
366 ----------------------------------------
367
368 Instead of populating a filesystem image for User Mode Linux from an existing
369 distribution installation, blank images can be created as follows:
370
371 uml-make-image --do-not-populate 4 512
372
373 Then, an initrd file can be used together with installation media - typically
374 an ISO file that would usually be burned onto a CD or DVD - such that a UML
375 instance can be booted and a distribution then installed into the blank images
376 from the installation media.
377
378 The initrd file is typically extracted from an ISO file (for example,
379 installer.iso) as follows (with superuser privileges):
380
381 mkdir installer
382 mount -o loop installer.iso installer
383 cp installer/initrd.gz .
384 umount installer
385
386 This assumes that initrd.gz is found at the top level of the installation
387 media's filesystem. It may also be found in a directory below the top level
388 such as install.386 (taking the i386 architecture as an example) on Debian
389 installation media.
390
391 The UML instance is then booted as follows:
392
393 uml-do 512M --net --initrd initrd.gz installer.iso
394
395 The blank images will appear as /dev/ubda and /dev/ubdb devices in the
396 instance, not merely as partitions, and so installers may ask you if you would
397 like to partition these devices still further.
398
399 The installation media will appear as /dev/ubdc and this may need to be
400 specified manually when an installer is attempting to read the installation
401 media from what it thinks is a CD-ROM drive.
402
403 Since the installer will most likely be designed for use on real hardware,
404 various operations will be performed that will fail in a UML environment. Of
405 particular importance is that of networking, and it may be necessary to
406 configure networking manually during any installation process, skip any update
407 steps requiring the network, and to perform additional configuration and
408 updates after the installation has been carried out.
409
410 Exiting an installer may be problematic since the installer may assume that
411 the installation media has been ejected from the system when it is, in fact,
412 still available after a reboot. To shut down the UML instance, obtain a shell
413 from the installer program and issue the "halt" command.
414
415 Once an installation has been performed using installation media, it should be
416 possible to omit the --initrd options when running uml-do on subsequent
417 occasions.
418
419 Using Graphical Desktop Environments with UML
420 ---------------------------------------------
421
422 It is possible to start a graphical desktop environment from within a User
423 Mode Linux instance and display the desktop on the host's display. In the host
424 environment, access to the display must be granted using a program such as
425 xhost. For example, for a UML instance whose network address is 192.168.0.98:
426
427 xhost +192.168.0.98
428
429 In the UML instance, the Xephyr program can be run to provide a display for
430 the graphical environment. For example, for a host that appears as
431 192.168.0.254 to the UML instance:
432
433 DISPLAY=192.168.0.254:0.0 Xephyr :1 -screen 1024x768 &
434
435 It should then be possible to start a desktop environment with the
436 Xephyr-based display specified as the appropriate display to use:
437
438 DISPLAY=:1 gnome-session &
439
440 Here, Xephyr has been started as screen :1.
441
442 Issues with Shared Memory
443 -------------------------
444
445 It is possible for User Mode Linux to just crash having exhausted the host
446 system's shared memory. This can be worked around by remounting tmpfs with
447 more space. For example:
448
449 sudo mount -t tmpfs tmpfs /dev/shm -o remount,size=805306368
450
451 This allocates 768MB (the figure is given in bytes) to tmpfs.
452
453 One bug related to User Mode Linux and Debian exists:
454
455 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=388128
456
457 And this Debian installer bug may be related to experiences with pbuilder and
458 other package installation activities:
459
460 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239758