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
310 Building User Mode Linux
311 ------------------------
312
313 To make a User Mode Linux executable, run the uml-build-linux script.
314
315 Enabling Networking for UML Instances
316 -------------------------------------
317
318 To enable networking for a UML instance, use the uml-net script:
319
320 sudo uml-net --start $USER
321
322 Here, $USER should be expanded to the name of the user running the above
323 command, not the root user.
324
325 To stop networking, use the same script:
326
327 sudo uml-net --stop
328
329 Entering or Starting UML Instances
330 ----------------------------------
331
332 To enter a UML instance, use the uml-do script, specifying an amount of memory
333 to allocate to the instance:
334
335 uml-do 512M
336
337 Specifying the --net option allows networking to be used by the instance, if
338 set up as described above:
339
340 uml-do 512M --net
341
342 Accessing UML Consoles
343 ----------------------
344
345 During the boot process, User Mode Linux should report a number of lines of
346 the following form:
347
348 Virtual console 1 assigned device '/dev/pts/3'
349
350 This indicates that to access console 1, the given device should be accessed.
351 This can be done using the screen command as follows:
352
353 screen /dev/pts/3
354
355 You may need to press Return/Enter to "wake up" the console in order to see a
356 login prompt.
357
358 Booting into UML from Installation Media
359 ----------------------------------------
360
361 Instead of populating a filesystem image for User Mode Linux from an existing
362 distribution installation, blank images can be created as follows:
363
364 uml-make-image --do-not-populate 4 512
365
366 Then, an initrd file can be used together with installation media - typically
367 an ISO file that would usually be burned onto a CD or DVD - such that a UML
368 instance can be booted and a distribution then installed into the blank images
369 from the installation media.
370
371 The initrd file is typically extracted from an ISO file (for example,
372 installer.iso) as follows (with superuser privileges):
373
374 mkdir installer
375 mount -o loop installer.iso installer
376 cp installer/initrd.gz .
377 umount installer
378
379 This assumes that initrd.gz is found at the top level of the installation
380 media's filesystem.
381
382 The UML instance is then booted as follows:
383
384 uml-do 512M --net --initrd initrd.gz installer.iso
385
386 The blank images will appear as /dev/ubda and /dev/ubdb devices in the
387 instance, not merely as partitions, and so installers may ask you if you would
388 like to partition these devices still further.
389
390 Once an installation has been performed using installation media, it should be
391 possible to omit the --initrd options when running uml-do on subsequent
392 occasions.
393
394 Using Graphical Desktop Environments with UML
395 ---------------------------------------------
396
397 It is possible to start a graphical desktop environment from within a User
398 Mode Linux instance and display the desktop on the host's display. In the host
399 environment, access to the display must be granted using a program such as
400 xhost. For example, for a UML instance whose network address is 192.168.0.98:
401
402 xhost +192.168.0.98
403
404 In the UML instance, the Xephyr program can be run to provide a display for
405 the graphical environment. For example, for a host that appears as
406 192.168.0.254 to the UML instance:
407
408 DISPLAY=192.168.0.254:0.0 Xephyr :1 -screen 1024x768 &
409
410 It should then be possible to start a desktop environment with the
411 Xephyr-based display specified as the appropriate display to use:
412
413 DISPLAY=:1 gnome-session &
414
415 Here, Xephyr has been started as screen :1.
416
417 Issues with Shared Memory
418 -------------------------
419
420 It is possible for User Mode Linux to just crash having exhausted the host
421 system's shared memory. This can be worked around by remounting tmpfs with
422 more space. For example:
423
424 sudo mount -t tmpfs tmpfs /dev/shm -o remount,size=805306368
425
426 This allocates 768MB (the figure is given in bytes) to tmpfs.
427
428 One bug related to User Mode Linux and Debian exists:
429
430 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=388128
431
432 And this Debian installer bug may be related to experiences with pbuilder and
433 other package installation activities:
434
435 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239758