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