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.
46 * Added support for UML instance construction from distribution
47 installations, along with networking support and a uml-net script.
48
49 Configuration
50 -------------
51
52 If the system defaults are not to be used, or if userinstall is not installed
53 as a system package, the userinstall-defaults file supplied with the
54 distribution may be edited to specify the nature and location of the personal
55 package manager.
56
57 The following settings can be edited:
58
59 USERINSTALL_ID This should reflect the distribution being used or, in
60 special cases, a different distribution. Examples
61 include Debian and Ubuntu.
62
63 USERINSTALL_CODENAME This should reflect the version of the distribution
64 being used and need only be altered in special
65 situations (such as the creation of a sandbox for
66 testing other distributions).
67
68 Examples of codenames include hardy and jaunty for
69 Ubuntu and lenny and squeeze for Debian. Note that the
70 setup process may not work with different distributions
71 due to library incompatibilities.
72
73 PACKAGEROOT The location of the personal package manager in the
74 filesystem.
75
76 See the /etc/lsb-release file for example values describing your own system,
77 with the DISTRIB prefix used instead of the USERINSTALL prefix for each of the
78 settings.
79
80 If a completely new userinstall-defaults file is created, it is essential that
81 the above variables be defined so that the scripts know where to create or to
82 find the personal package manager.
83
84 Creating a Personal Package Manager
85 -----------------------------------
86
87 In order to install packages as a non-root user, first invoke the user-setup
88 script; this will create and initialise a basic Debian system with a basic set
89 of packages installed. For example, with userinstall installed as a system
90 package, using the system defaults:
91
92 user-setup
93
94 It is possible to override the "template" for the system by specifying a
95 "mirror" location. This is useful if you have the CD or DVD image for the
96 distribution already mounted in the filesystem. For example:
97
98 user-setup file:///cdrom
99
100 sudo mount -o loop /home/me/downloads/kubuntu-7.04-alternate-i386.iso /tmp/cdrom
101 user-setup file:///tmp/cdrom
102
103 An URI must be specified as the "mirror" location, not a normal filename.
104
105 Once the installation is complete, some post-installation is necessary:
106
107 user-postsetup
108
109 If a different distribution is being used for the package manager than that
110 being run on the system, it might be necessary to specify a country code so
111 that the configuration of package repositories can be performed successfully.
112 For example, for repositories mirrored in the United Kingdom (UK):
113
114 user-postsetup uk
115
116 At this point, the package manager should be ready to use.
117
118 Adding Package Repositories to the Package Manager
119 --------------------------------------------------
120
121 To get access to repositories of packages beyond those provided by the basic
122 distribution, edit the /etc/apt/sources.list file inside the system. The
123 user-path script can help you find the exact location of the file:
124
125 user-path /etc/apt/sources.list
126
127 And you can edit the file directly with a text editor (such as vi) as follows:
128
129 vi `user-path /etc/apt/sources.list`
130
131 Installing Packages
132 -------------------
133
134 To install packages from other repositories, invoke the user-do script and
135 specify the apt-get program together with options expected by that program.
136 For example:
137
138 user-do apt-get --help
139 user-do apt-get update
140
141 Packages can then be installed. For example:
142
143 user-do apt-get install python-cmdsyntax
144
145 Provided that the specified packages are known and their dependencies can be
146 met, they will be installed into the system.
147
148 Installing Single Packages
149 --------------------------
150
151 To install individual package files, first copy them into the package manager
152 directory hierarchy. For example:
153
154 cp python-cmdsyntax_0.91-0ubuntu2_all.deb `user-path /tmp`
155
156 The invoke the dpkg program through the user-do script as follows:
157
158 user-do dpkg -i /tmp/python-cmdsyntax_0.91-0ubuntu2_all.deb
159
160 Using Packages
161 --------------
162
163 Unlike most packages installed in the usual way by the root user, the installed
164 packages will not reside within a directory hierarchy rooted at / - the top of
165 the filesystem. Instead, they will reside in a location such as the following:
166
167 /home/me/.userinstall
168 /tmp/packages
169
170 (The precise location may be found by running the user-path script.)
171
172 Consequently, to make use of the installed software, it may be necessary to
173 edit your environment in a number of ways so that it may be located and
174 correctly loaded, initialised and executed.
175
176 Using Python Packages
177 ---------------------
178
179 Installed Python packages may be made available to Python by defining the
180 PYTHONPATH to include the directories usually searched by Python, but which
181 are actually located within the personal package management environment. For
182 example, with the Python 2.5 site-packages directory:
183
184 PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5
185
186 More complicated extension modules may require further adjustments to the
187 LD_LIBRARY_PATH and PYTHONPATH variables:
188
189 export LD_LIBRARY_PATH=`user-path /usr/lib`
190 export PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/`
191 export PYTHONPATH=${PYTHONPATH}:`user-path /var/lib/python-support/python2.5`
192
193 Entering the Package Manager
194 ----------------------------
195
196 It is also possible to administer the package manager from within the
197 installation:
198
199 user-do
200
201 This should provide a "root" prompt which can then be used to issue commands
202 within the package manager environment. For example:
203
204 apt-get update
205
206 Constructing UML Instances
207 --------------------------
208
209 For some applications, it can be desirable to provide a completely isolated
210 environment for package installation and testing. This can be performed using
211 the User Mode Linux (UML) software.
212
213 To convert a package manager installation into a UML instance, start with the
214 user-to-uml script which changes the installation's configuration in a number
215 of areas:
216
217 user-to-uml
218
219 Then, as a privileged user, run the uml-setupdev script to initialise some
220 UML-specific device files:
221
222 sudo uml-setupdev
223
224 Since UML needs to see its filesystems as images, not directories within an
225 existing filesystem, the uml-setupfs script needs to create these image files.
226 For example, to create a root filesystem 1GB in size, along with a swap file
227 512MB in size:
228
229 uml-setupfs 4 512
230
231 Again, as a privileged user, these images are then populated with the package
232 manager contents as follows:
233
234 sudo uml-postsetupfs
235
236 NOTE: Add Linux build process.
237
238 Enabling Networking for UML Instances
239 -------------------------------------
240
241 To enable networking for a UML instance, use the uml-net script:
242
243 sudo uml-net --start $USER
244
245 Here, $USER should be expanded to the name of the user running the above
246 command, not the root user.
247
248 To stop networking, use the same script:
249
250 sudo uml-net --stop
251
252 Entering or Starting UML Instances
253 ----------------------------------
254
255 To enter a UML instance, use the uml-do script:
256
257 uml-do