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
57 New in userinstall 0.2.1 (Changes since userinstall 0.2)
58 --------------------------------------------------------
59
60 * Added more User Mode Linux documentation.
61
62 New in userinstall 0.2 (Changes since userinstall 0.1)
63 ------------------------------------------------------
64
65 * Adopted lsb-release environment variables instead of new ones like
66 DISTNAME, exposing derivatives of these variables by default.
67 * Added explicit keyring package installation.
68 * Added -do scripts for configuring and entering the chroot.
69 * Removed specific apt- and dpkg-related scripts, replacing them with the
70 general -do scripts.
71 * Added --root options to certain scripts in order to support normal chroot
72 installations. Added --dev option for bind mounting of /dev in normal
73 chroot installations.
74 * Added support for UML instance construction from distribution
75 installations, along with networking support and a uml-net script. Also
76 added some support for booting from initrd files and installation media
77 image files.
78
79 Configuration
80 -------------
81
82 If the system defaults are not to be used, or if userinstall is not installed
83 as a system package, the userinstall-defaults file supplied with the
84 distribution may be edited to specify the nature and location of the personal
85 package manager.
86
87 The following settings can be edited:
88
89 USERINSTALL_ID This should reflect the distribution being used or, in
90 special cases, a different distribution. Examples
91 include Debian and Ubuntu.
92
93 USERINSTALL_CODENAME This should reflect the version of the distribution
94 being used and need only be altered in special
95 situations (such as the creation of a sandbox for
96 testing other distributions).
97
98 Examples of codenames include hardy and jaunty for
99 Ubuntu and lenny and squeeze for Debian. Note that the
100 setup process may not work with different distributions
101 due to library incompatibilities.
102
103 PACKAGEROOT The location of the personal package manager in the
104 filesystem.
105
106 See the /etc/lsb-release file for example values describing your own system,
107 with the DISTRIB prefix used instead of the USERINSTALL prefix for each of the
108 settings.
109
110 If a completely new userinstall-defaults file is created, it is essential that
111 the above variables be defined so that the scripts know where to create or to
112 find the personal package manager. Typically, a new userinstall-defaults file
113 will reside in the current directory when the different userinstall commands
114 are being issued.
115
116 Creating a Personal Package Manager
117 -----------------------------------
118
119 In order to install packages as a non-root user, first invoke the user-setup
120 script; this will create and initialise a basic Debian system with a basic set
121 of packages installed. For example, with userinstall installed as a system
122 package, using the system defaults:
123
124 user-setup
125
126 It is possible to override the "template" for the system by specifying a
127 "mirror" location. This is useful if you have the CD or DVD image for the
128 distribution already mounted in the filesystem. For example:
129
130 user-setup file:///cdrom
131
132 sudo mount -o loop /home/me/downloads/kubuntu-7.04-alternate-i386.iso /tmp/cdrom
133 user-setup file:///tmp/cdrom
134
135 A URL must be specified as the "mirror" location, not a normal filename.
136
137 Once the installation is complete, some post-installation is necessary:
138
139 user-postsetup
140
141 If a different distribution is being used for the package manager than that
142 being run on the system, it might be necessary to specify a country code so
143 that the configuration of package repositories can be performed successfully.
144 For example, for repositories mirrored in the United Kingdom (UK):
145
146 user-postsetup uk
147
148 At this point, the package manager should be ready to use.
149
150 Adding Package Repositories to the Package Manager
151 --------------------------------------------------
152
153 To get access to repositories of packages beyond those provided by the basic
154 distribution, edit the /etc/apt/sources.list file inside the system. The
155 user-path script can help you find the exact location of the file:
156
157 user-path /etc/apt/sources.list
158
159 And you can edit the file directly with a text editor (such as vi) as follows:
160
161 vi `user-path /etc/apt/sources.list`
162
163 Installing Packages
164 -------------------
165
166 To install packages from other repositories, invoke the user-do script and
167 specify the apt-get program together with options expected by that program.
168 For example:
169
170 user-do apt-get --help
171 user-do apt-get update
172
173 Packages can then be installed. For example:
174
175 user-do apt-get install python-cmdsyntax
176
177 Provided that the specified packages are known and their dependencies can be
178 met, they will be installed into the system.
179
180 Installing Single Packages
181 --------------------------
182
183 To install individual package files, first copy them into the package manager
184 directory hierarchy. For example:
185
186 cp python-cmdsyntax_0.91-0ubuntu2_all.deb `user-path /tmp`
187
188 The invoke the dpkg program through the user-do script as follows:
189
190 user-do dpkg -i /tmp/python-cmdsyntax_0.91-0ubuntu2_all.deb
191
192 Using Packages
193 --------------
194
195 Unlike most packages installed in the usual way by the root user, the installed
196 packages will not reside within a directory hierarchy rooted at / - the top of
197 the filesystem. Instead, they will reside in a location such as the following:
198
199 /home/me/.userinstall
200 /tmp/packages
201
202 (The precise location may be found by running the user-path script.)
203
204 Consequently, to make use of the installed software, it may be necessary to
205 edit your environment in a number of ways so that it may be located and
206 correctly loaded, initialised and executed.
207
208 Using Python Packages
209 ---------------------
210
211 Installed Python packages may be made available to Python by defining the
212 PYTHONPATH to include the directories usually searched by Python, but which
213 are actually located within the personal package management environment. For
214 example, with the Python 2.5 site-packages directory:
215
216 PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5
217
218 More complicated extension modules may require further adjustments to the
219 LD_LIBRARY_PATH and PYTHONPATH variables:
220
221 export LD_LIBRARY_PATH=`user-path /usr/lib`
222 export PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/`
223 export PYTHONPATH=${PYTHONPATH}:`user-path /var/lib/python-support/python2.5`
224
225 Entering the Package Manager
226 ----------------------------
227
228 It is also possible to administer the package manager from within the
229 installation:
230
231 user-do
232
233 This should provide a "root" prompt which can then be used to issue commands
234 within the package manager environment. For example:
235
236 apt-get update && apt-get upgrade
237
238 Creating and Entering a Package Manager in Root Mode
239 ----------------------------------------------------
240
241 The user-setup, user-postsetup and user-do scripts also support a --root
242 option which sets up a package manager for a user with root privileges. To
243 set up such an installation, the following commands can be used:
244
245 user-setup --root
246 user-postsetup --root
247
248 Entering the installation is done using the user-do script:
249
250 user-do --root
251
252 Note that in root mode, the /proc and /sys filesystems are mounted within the
253 installation. Care must be taken not to delete the contents of these
254 directories within the installation while the above command is running;
255 otherwise, this can potentially damage the main operating system installation
256 on your computer.
257
258 Using the Host's Device Filesystem
259 ----------------------------------
260
261 In root mode, the /dev filesystem on the host can be mounted by using the
262 --dev option with user-do:
263
264 user-do --root --dev
265
266 Note that care must be taken not to delete the contents of this directory
267 within the installation while the above command is running.
268
269 Enabling Audio in Root Mode
270 ---------------------------
271
272 Together with the --root and --dev options, audio can be enabled for
273 applications within an installation by adding users to the audio group in
274 /etc/group. In addition, it may be necessary to run an audio manager daemon
275 depending on the system used to manage the audio on the host.
276
277 For example, the artsd package may need installing in order to make the
278 corresponding artsdsp program available to applications within the package
279 manager.
280
281 Configuration of User Mode Linux Instances
282 ------------------------------------------
283
284 For some applications, it can be desirable to provide a completely isolated
285 environment for package installation and testing. This can be performed using
286 the User Mode Linux (UML) software.
287
288 Alongside the userinstall-defaults file, a userinstall-defaults-uml file must
289 be made available. As with the generic userinstall-defaults file, the
290 UML-specific configuration in userinstall-defaults-uml must be edited to
291 reflect the desired settings such that appropriate network addresses are used
292 along with a suitable Linux kernel.
293
294 Constructing UML Instances
295 --------------------------
296
297 Since UML needs to see its filesystems as images, not directories within an
298 existing filesystem, the uml-make-image script needs to create these image
299 files. For example, to create a root filesystem 4GB in size, along with a swap
300 file 512MB in size:
301
302 uml-make-image 4 512
303
304 This will create a UML instance from an existing package manager installation.
305
306 Building User Mode Linux
307 ------------------------
308
309 To make a User Mode Linux executable, run the uml-build-linux script.
310
311 Enabling Networking for UML Instances
312 -------------------------------------
313
314 To enable networking for a UML instance, use the uml-net script:
315
316 sudo uml-net --start $USER
317
318 Here, $USER should be expanded to the name of the user running the above
319 command, not the root user.
320
321 To stop networking, use the same script:
322
323 sudo uml-net --stop
324
325 Entering or Starting UML Instances
326 ----------------------------------
327
328 To enter a UML instance, use the uml-do script, specifying an amount of memory
329 to allocate to the instance:
330
331 uml-do 512M
332
333 Specifying the --net option allows networking to be used by the instance, if
334 set up as described above:
335
336 uml-do 512M --net
337
338 Booting into UML from Installation Media
339 ----------------------------------------
340
341 Instead of populating a filesystem image for User Mode Linux from an existing
342 distribution installation, blank images can be created as follows:
343
344 uml-make-image --do-not-populate 4 512
345
346 Then, an initrd file can be used together with installation media - typically
347 an ISO file that would usually be burned onto a CD or DVD - such that a UML
348 instance can be booted and a distribution then installed into the blank images
349 from the installation media.
350
351 The initrd file is typically extracted from an ISO file (for example,
352 installer.iso) as follows (with superuser privileges):
353
354 mkdir installer
355 mount -o loop installer.iso installer
356 cp installer/initrd.gz .
357 umount installer
358
359 This assumes that initrd.gz is found at the top level of the installation
360 media's filesystem.
361
362 The UML instance is then booted as follows:
363
364 uml-do 512M --net --initrd initrd.gz installer.iso
365
366 The blank images will appear as /dev/ubda and /dev/ubdb devices in the
367 instance, not merely as partitions, and so installers may ask you if you would
368 like to partition these devices still further.
369
370 Once an installation has been performed using installation media, it should be
371 possible to omit the --initrd options when
372
373 Using Graphical Desktop Environments with UML
374 ---------------------------------------------
375
376 It is possible to start a graphical desktop environment from within a User
377 Mode Linux instance and display the desktop on the host's display. In the host
378 environment, access to the display must be granted using a program such as
379 xhost. For example, for a UML instance whose network address is 192.168.0.98:
380
381 xhost +192.168.0.98
382
383 In the UML instance, the Xephyr program can be run to provide a display for
384 the graphical environment. For example, for a host that appears as
385 192.168.0.254 to the UML instance:
386
387 DISPLAY=192.168.0.254:0.0 Xephyr :1 -screen 1024x768 &
388
389 It should then be possible to start a desktop environment with the
390 Xephyr-based display specified as the appropriate display to use:
391
392 DISPLAY=:1 gnome-session &
393
394 Here, Xephyr has been started as screen :1.
395
396 Issues with Shared Memory
397 -------------------------
398
399 It is possible for User Mode Linux to just crash having exhausted the host
400 system's shared memory. This can be worked around by remounting tmpfs with
401 more space. For example:
402
403 sudo mount -t tmpfs tmpfs /dev/shm -o remount,size=805306368
404
405 This allocates 768MB (the figure is given in bytes) to tmpfs.
406
407 One bug related to User Mode Linux and Debian exists:
408
409 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=388128
410
411 And this Debian installer bug may be related to experiences with pbuilder and
412 other package installation activities:
413
414 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239758