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