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 Before making an image, make sure that you have set a root password in the
302 existing filesystem. Otherwise, you will not be able to log into the UML
303 instance. The following commands will achieve this:
304
305 user-do --root
306 passwd
307 exit
308
309 Since UML needs to see its filesystems as images, not directories within an
310 existing filesystem, the uml-make-image script needs to create these image
311 files. For example, to create a root filesystem 4GB in size, along with a swap
312 file 512MB in size:
313
314 uml-make-image 4 512
315
316 This will create a UML instance from an existing package manager installation.
317 Where a root mode package filesystem has been created, use the following
318 command:
319
320 uml-make-image --root 4 512
321
322 However, if a UML instance will be populated using installation media
323 (described below), the following is more suitable:
324
325 uml-make-image --no-fs 4 512
326
327 This does not create filesystems but instead leaves it to the installer to
328 partition the files created.
329
330 Resizing Filesystems
331 --------------------
332
333 To change the size of filesystems later on, use the resize2fs command after
334 having checked the filesystem. For example, with a root filesystem file called
335 root-root.fs and a desired new filesystem size of 6GB:
336
337 /sbin/e2fsck -f root-root.fs
338 /sbin/resize2fs root-root.fs 6G
339
340 Obviously, these commands will only work with ext2 family filesystems.
341
342 Building User Mode Linux
343 ------------------------
344
345 To make a User Mode Linux executable, run the uml-linux-build script, with the
346 --root option being necessary to install modules into a root filesystem:
347
348 uml-linux-build --root
349
350 Enabling Networking for UML Instances
351 -------------------------------------
352
353 To enable networking for a UML instance, use the uml-net script:
354
355 sudo uml-net --start $USER
356
357 Here, $USER should be expanded to the name of the user running the above
358 command, not the root user. If invoked as above using sudo, the name of the
359 invoking user should be provided by $USER because the shell will expand that
360 variable before any program is run.
361
362 To stop networking, use the same script:
363
364 sudo uml-net --stop
365
366 Entering or Starting UML Instances
367 ----------------------------------
368
369 To enter a UML instance, use the uml-do script, specifying an amount of memory
370 to allocate to the instance:
371
372 uml-do 512M
373
374 Specifying the --net option allows networking to be used by the instance, if
375 set up as described above:
376
377 uml-do 512M --net
378
379 Accessing UML Consoles
380 ----------------------
381
382 During the boot process, User Mode Linux should report a number of lines of
383 the following form:
384
385 Virtual console 1 assigned device '/dev/pts/3'
386
387 This indicates that to access console 1, the given device should be accessed.
388 This can be done using the screen command as follows:
389
390 screen /dev/pts/3
391
392 You may need to press Return/Enter to "wake up" the console in order to see a
393 login prompt.
394
395 Booting into UML from Installation Media
396 ----------------------------------------
397
398 Instead of populating a filesystem image for User Mode Linux from an existing
399 distribution installation, blank images can be created as follows:
400
401 uml-make-image --no-fs 4 512
402
403 Then, an initrd file can be used together with installation media - typically
404 an ISO file that would usually be burned onto a CD or DVD - such that a UML
405 instance can be booted and a distribution then installed into the blank images
406 from the installation media.
407
408 The initrd file is typically extracted from an ISO file (for example,
409 installer.iso) as follows (with superuser privileges):
410
411 mkdir installer
412 mount -o loop installer.iso installer
413 cp installer/initrd.gz .
414 umount installer
415
416 This assumes that initrd.gz is found at the top level of the installation
417 media's filesystem. It may also be found in a directory below the top level
418 such as install.386 (taking the i386 architecture as an example) on Debian
419 installation media.
420
421 The UML instance is then booted as follows:
422
423 uml-do 512M --net --initrd initrd.gz installer.iso
424
425 The blank images will appear as /dev/ubda and /dev/ubdb devices in the
426 instance, not merely as partitions, and so installers may ask you if you would
427 like to partition these devices still further.
428
429 The installation media will appear as /dev/ubdc and this may need to be
430 specified manually when an installer is attempting to read the installation
431 media from what it thinks is a CD-ROM drive.
432
433 Since the installer will most likely be designed for use on real hardware,
434 various operations will be performed that will fail in a UML environment. Of
435 particular importance is that of networking, and it may be necessary to
436 configure networking manually during any installation process, skip any update
437 steps requiring the network, and to perform additional configuration and
438 updates after the installation has been carried out.
439
440 Exiting an installer may be problematic since the installer may assume that
441 the installation media has been ejected from the system when it is, in fact,
442 still available after a reboot. To shut down the UML instance, obtain a shell
443 from the installer program and issue the "halt" command.
444
445 Once an installation has been performed using installation media, it should be
446 possible to omit the --initrd options when running uml-do on subsequent
447 occasions.
448
449 Using Graphical Desktop Environments with UML
450 ---------------------------------------------
451
452 It is possible to start a graphical desktop environment from within a User
453 Mode Linux instance and display the desktop on the host's display. In the host
454 environment, access to the display must be granted using a program such as
455 xhost. For example, for a UML instance whose network address is 192.168.0.98:
456
457 xhost +192.168.0.98
458
459 In the UML instance, the Xephyr program can be run to provide a display for
460 the graphical environment. For example, for a host that appears as
461 192.168.0.254 to the UML instance:
462
463 DISPLAY=192.168.0.254:0.0 Xephyr :1 -screen 1024x768 &
464
465 It should then be possible to start a desktop environment with the
466 Xephyr-based display specified as the appropriate display to use:
467
468 DISPLAY=:1 gnome-session &
469
470 Here, Xephyr has been started as screen :1.
471
472 Issues with Shared Memory
473 -------------------------
474
475 It is possible for User Mode Linux to just crash having exhausted the host
476 system's shared memory. This can be worked around by remounting tmpfs with
477 more space. For example:
478
479 sudo mount -t tmpfs tmpfs /dev/shm -o remount,size=805306368
480
481 This allocates 768MB (the figure is given in bytes) to tmpfs.
482
483 One bug related to User Mode Linux and Debian exists:
484
485 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=388128
486
487 And this Debian installer bug may be related to experiences with pbuilder and
488 other package installation activities:
489
490 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239758