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