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