track document samples used

1 files changed, 643 insertions, 0 deletions

diff --git a/markup/pod/live-manual/media/text/ro/user_customization-packages.ssi b/markup/pod/live-manual/media/text/ro/user_customization-packages.ssi
new file mode 100644
index 0000000..dd6bd88
--- /dev/null
+++ b/markup/pod/live-manual/media/text/ro/user_customization-packages.ssi
@@ -0,0 +1,643 @@
+:B~ Customizing package installation
+
+1~customizing-package-installation Customizing package installation
+
+Perhaps the most basic customization of a live system is the selection of
+packages to be included in the image. This chapter guides you through the
+various build-time options to customize live-build's installation of
+packages. The broadest choices influencing which packages are available to
+install in the image are the distribution and archive areas. To ensure
+decent download speeds, you should choose a nearby distribution mirror. You
+can also add your own repositories for backports, experimental or custom
+packages, or include packages directly as files. You can define lists of
+packages, including metapackages which will install many related packages at
+once, such as packages for a particular desktop or language. Finally, a
+number of options give some control over /{apt}/, or if you prefer,
+/{aptitude}/, at build time when packages are installed. You may find these
+handy if you use a proxy, want to disable installation of recommended
+packages to save space, or need to control which versions of packages are
+installed via APT pinning, to name a few possibilities.
+
+2~ Package sources
+
+3~ Distribution, archive areas and mode
+
+The distribution you choose has the broadest impact on which packages are
+available to include in your live image. Specify the codename, which
+defaults to ${testing} for the ${testing} version of live-build. Any current
+distribution carried in the archive may be specified by its codename
+here. (See {Terms}#terms for more details.) The #{--distribution}# option
+not only influences the source of packages within the archive, but also
+instructs live-build to behave as needed to build each supported
+distribution. For example, to build against the *{unstable}* release, sid,
+specify:
+
+code{
+
+ $ lb config --distribution sid
+
+}code
+
+Within the distribution archive, archive areas are major divisions of the
+archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only
+#{main}# contains software that is part of the Debian distribution, hence
+that is the default. One or more values may be specified, e.g.
+
+code{
+
+ $ lb config --archive-areas "main contrib non-free"
+
+}code
+
+Experimental support is available for some Debian derivatives through a
+#{--mode}# option. By default, this option is set to #{debian}# only if you
+are building on a Debian or on an unknown system. If #{lb config}# is
+invoked on any of the supported derivatives, it will default to create an
+image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode,
+the distribution names and archive areas for the specified derivative are
+supported instead of the ones for Debian. The mode also modifies live-build
+behaviour to suit the derivatives.
+
+*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves.
+
+3~ Distribution mirrors
+
+The Debian archive is replicated across a large network of mirrors around
+the world so that people in each region can choose a nearby mirror for best
+download speed. Each of the #{--mirror-*}# options governs which
+distribution mirror is used at various stages of the build. Recall from
+{Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is
+when the chroot is initially populated by /{debootstrap}/ with a minimal
+system, and the *{chroot}* stage is when the chroot used to construct the
+live system's filesystem is built. Thus, the corresponding mirror switches
+are used for those stages, and later, in the *{binary}* stage, the
+#{--mirror-binary}# and #{--mirror-binary-security}# values are used,
+superseding any mirrors used in an earlier stage.
+
+3~distribution-mirrors-build-time Distribution mirrors used at build time
+
+To set the distribution mirrors used at build time to point at a local
+mirror, it is sufficient to set #{--mirror-bootstrap}# and
+#{--mirror-chroot-security}# as follows.
+
+code{
+
+ $ lb config --mirror-bootstrap http://localhost/debian/ \
+          --mirror-chroot-security http://localhost/debian-security/
+
+}code
+
+The chroot mirror, specified by #{--mirror-chroot}#, defaults to the
+#{--mirror-bootstrap}# value.
+
+3~ Distribution mirrors used at run time
+
+The #{--mirror-binary*}# options govern the distribution mirrors placed in
+the binary image. These may be used to install additional packages while
+running the live system. The defaults employ #{httpredir.debian.org}#, a
+service that chooses a geographically close mirror based, among other
+things, on the user's IP family and the availability of the mirrors. This is
+a suitable choice when you cannot predict which mirror will be best for all
+of your users. Or you may specify your own values as shown in the example
+below. An image built from this configuration would only be suitable for
+users on a network where "#{mirror}#" is reachable.
+
+code{
+
+ $ lb config --mirror-binary http://mirror/debian/ \
+          --mirror-binary-security http://mirror/debian-security/ \
+          --mirror-binary-backports http://mirror/debian-backports/
+
+}code
+
+3~additional-repositories Additional repositories
+
+You may add more repositories, broadening your package choices beyond what
+is available in your target distribution. These may be, for example, for
+backports, experimental or custom packages. To configure additional
+repositories, create #{config/archives/your-repository.list.chroot}#, and/or
+#{config/archives/your-repository.list.binary}# files. As with the
+#{--mirror-*}# options, these govern the repositories used in the *{chroot}*
+stage when building the image, and in the *{binary}* stage, i.e. for use
+when running the live system.
+
+For example, #{config/archives/live.list.chroot}# allows you to install
+packages from the debian-live snapshot repository at live system build time.
+
+code{
+
+ deb http://live-systems.org/ sid-snapshots main contrib non-free
+
+}code
+
+If you add the same line to #{config/archives/live.list.binary}#, the
+repository will be added to your live system's #{/etc/apt/sources.list.d/}#
+directory.
+
+If such files exist, they will be picked up automatically.
+
+You should also put the GPG key used to sign the repository into
+#{config/archives/your-repository.key.{binary,chroot}}# files.
+
+Should you need custom APT pinning, such APT preferences snippets can be
+placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and
+will be automatically added to your live system's
+#{/etc/apt/preferences.d/}# directory.
+
+2~choosing-packages-to-install Choosing packages to install
+
+There are a number of ways to choose which packages live-build will install
+in your image, covering a variety of different needs. You can simply name
+individual packages to install in a package list. You can also use
+metapackages in those lists, or select them using package control file
+fields. And finally, you may place package files in your #{config/}# tree,
+which is well suited to testing of new or experimental packages before they
+are available from a repository.
+
+3~package-lists Package lists
+
+Package lists are a powerful way of expressing which packages should be
+installed. The list syntax supports conditional sections which makes it easy
+to build lists and adapt them for use in multiple configurations. Package
+names may also be injected into the list using shell helpers at build time.
+
+*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details.
+
+3~using-metapackages Using metapackages
+
+The simplest way to populate your package list is to use a task metapackage
+maintained by your distribution. For example:
+
+code{
+
+ $ lb config
+ $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot
+
+}code
+
+This supercedes the older predefined list method supported in #{live-build}#
+2.x. Unlike predefined lists, task metapackages are not specific to the Live
+System project. Instead, they are maintained by specialist working groups
+within the distribution and therefore reflect the consensus of each group
+about which packages best serve the needs of the intended users. They also
+cover a much broader range of use cases than the predefined lists they
+replace.
+
+All task metapackages are prefixed #{task-}#, so a quick way to determine
+which are available (though it may contain a handful of false hits that
+match the name but aren't metapackages) is to match on the package name
+with:
+
+code{
+
+ $ apt-cache search --names-only ^task-
+
+}code
+
+In addition to these, you will find other metapackages with various
+purposes. Some are subsets of broader task packages, like #{gnome-core}#,
+while others are individual specialized parts of a Debian Pure Blend, such
+as the #{education-*}# metapackages. To list all metapackages in the
+archive, install the #{debtags}# package and list all packages with the
+#{role::metapackage}# tag as follows:
+
+code{
+
+ $ debtags search role::metapackage
+
+}code
+
+3~ Local package lists
+
+Whether you list metapackages, individual packages, or a combination of
+both, all local package lists are stored in #{config/package-lists/}#. Since
+more than one list can be used, this lends itself well to modular
+designs. For example, you may decide to devote one list to a particular
+choice of desktop, another to a collection of related packages that might as
+easily be used on top of a different desktop. This allows you to experiment
+with different combinations of sets of packages with a minimum of fuss,
+sharing common lists between different live image projects.
+
+Package lists that exist in this directory need to have a #{.list}# suffix
+in order to be processed, and then an additional stage suffix, #{.chroot}#
+or #{.binary}# to indicate which stage the list is for.
+
+*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium.
+
+3~ Local binary package lists
+
+To make a binary stage list, place a file suffixed with #{.list.binary}# in
+#{config/package-lists/}#. These packages are not installed in the live
+filesystem, but are included on the live medium under #{pool/}#. You would
+typically use such a list with one of the non-live installer variants. As
+mentioned above, if you want this list to be the same as your chroot stage
+list, simply use the #{.list}# suffix by itself.
+
+3~generated-package-lists Generated package lists
+
+It sometimes happens that the best way to compose a list is to generate it
+with a script. Any line starting with an exclamation point indicates a
+command to be executed within the chroot when the image is built. For
+example, one might include the line #{! grep-aptavail -n -sPackage
+-FPriority standard | sort}# in a package list to produce a sorted list of
+available packages with #{Priority: standard}#.
+
+In fact, selecting packages with the #{grep-aptavail}# command (from the
+#{dctrl-tools}# package) is so useful that #{live-build}# provides a
+#{Packages}# helper script as a convenience. This script takes two
+arguments: #{field}# and #{pattern}#. Thus, you can create a list with the
+following contents:
+
+code{
+
+ $ lb config
+ $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot
+
+}code
+
+3~ Using conditionals inside package lists
+
+Any of the live-build configuration variables stored in #{config/*}# (minus
+the #{LB_}# prefix) may be used in conditional statements in package
+lists. Generally, this means any #{lb config}# option uppercased and with
+dashes changed to underscores. But in practice, it is only the ones that
+influence package selection that make sense, such as #{DISTRIBUTION}#,
+#{ARCHITECTURES}# or #{ARCHIVE_AREAS}#.
+
+For example, to install #{ia32-libs}# if the #{--architectures amd64}# is
+specified:
+
+code{
+
+ #if ARCHITECTURES amd64
+ ia32-libs
+ #endif
+
+}code
+
+You may test for any one of a number of values, e.g. to install
+/{memtest86+}/ if either #{--architectures i386}# or #{--architectures
+amd64}# is specified:
+
+code{
+
+ #if ARCHITECTURES i386 amd64
+ memtest86+
+ #endif
+
+}code
+
+You may also test against variables that may contain more than one value,
+e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified
+via #{--archive-areas}#:
+
+code{
+
+ #if ARCHIVE_AREAS contrib non-free
+ vrms
+ #endif
+
+}code
+
+The nesting of conditionals is not supported.
+
+% FIXME:
+
+3~ Removing packages at install time
+
+You can list packages in files with #{.list.chroot_live}# and
+#{.list.chroot_install}# suffixes inside the #{config/package-lists}#
+directory. If both a live and an install list exist, the packages in the
+#{.list.chroot_live}# list are removed with a hook after the installation
+(if the user uses the installer). The packages in the
+#{.list.chroot_install}# list are present both in the live system and in the
+installed system. This is a special tweak for the installer and may be
+useful if you have #{--debian-installer live}# set in your config, and wish
+to remove live system-specific packages at install time.
+
+3~desktop-and-language-tasks Desktop and language tasks
+
+Desktop and language tasks are special cases that need some extra planning
+and configuration. Live images are different from Debian Installer images in
+this respect. In the Debian Installer, if the medium was prepared for a
+particular desktop environment flavour, the corresponding task will be
+automatically installed. Thus, there are internal #{gnome-desktop}#,
+#{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which
+are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for
+tasks for languages, but the user's language choice during the install
+influences the selection of corresponding language tasks.
+
+When developing a desktop live image, the image typically boots directly to
+a working desktop, the choices of both desktop and default language having
+been made at build time, not at run time as in the case of the Debian
+Installer. That's not to say that a live image couldn't be built to support
+multiple desktops or multiple languages and offer the user a choice, but
+that is not live-build's default behaviour.
+
+Because there is no provision made automatically for language tasks, which
+include such things as language-specific fonts and input-method packages, if
+you want them, you need to specify them in your configuration. For example,
+a GNOME desktop image containing support for German might include these task
+metapackages:
+
+code{
+
+ $ lb config
+ $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot
+ $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot
+
+}code
+
+3~kernel-flavour-and-version Kernel flavour and version
+
+One or more kernel flavours will be included in your image by default,
+depending on the architecture. You can choose different flavours via the
+#{--linux-flavours}# option. Each flavour is suffixed to the default stub
+#{linux-image}# to form each metapackage name which in turn depends on an
+exact kernel package to be included in your image.
+
+Thus by default, an #{amd64}# architecture image will include the
+#{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture
+image will include the #{linux-image-586}# metapackage.
+
+When more than one kernel package version is available in your configured
+archives, you can specify a different kernel package name stub with the
+#{--linux-packages}# option. For example, supposing you are building an
+#{amd64}# architecture image and add the experimental archive for testing
+purposes so you can install the #{linux-image-3.18.0-trunk-amd64}#
+kernel. You would configure that image as follows:
+
+code{
+
+ $ lb config --linux-packages linux-image-3.18.0-trunk
+ $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot
+
+}code
+
+3~custom-kernels Custom kernels
+
+You can build and include your own custom kernels, so long as they are
+integrated within the Debian package management system. The live-build
+system does not support kernels not built as #{.deb}# packages.
+
+The proper and recommended way to deploy your own kernel packages is to
+follow the instructions in the #{kernel-handbook}#. Remember to modify the
+ABI and flavour suffixes appropriately, then include a complete build of the
+#{linux}# and matching #{linux-latest}# packages in your repository.
+
+If you opt to build the kernel packages without the matching metapackages,
+you need to specify an appropriate #{--linux-packages}# stub as discussed in
+{Kernel flavour and version}#kernel-flavour-and-version. As we explain in
+{Installing modified or third-party
+packages}#installing-modified-or-third-party-packages, it is best if you
+include your custom kernel packages in your own repository, though the
+alternatives discussed in that section work as well.
+
+It is beyond the scope of this document to give advice on how to customize
+your kernel. However, you must at least ensure your configuration satisfies
+these minimum requirements:
+
+_* Use an initial ramdisk.
+
+_* Include the union filesystem module (i.e. usually #{aufs}#).
+
+_* Include any other filesystem modules required by your configuration
+(i.e. usually #{squashfs}#).
+
+2~installing-modified-or-third-party-packages Installing modified or
+third-party packages
+
+While it is against the philosophy of a live system, it may sometimes be
+necessary to build a live system with modified versions of packages that are
+in the Debian repository. This may be to modify or support additional
+features, languages and branding, or even to remove elements of existing
+packages that are undesirable. Similarly, "third-party" packages may be used
+to add bespoke and/or proprietary functionality.
+
+This section does not cover advice regarding building or maintaining
+modified packages. Joachim Breitner's 'How to fork privately' method from
+http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html
+may be of interest, however. The creation of bespoke packages is covered in
+the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/
+and elsewhere.
+
+There are two ways of installing modified custom packages:
+
+_* #{packages.chroot}#
+
+_* Using a custom APT repository
+
+Using #{packages.chroot}# is simpler to achieve and useful for "one-off"
+customizations but has a number of drawbacks, while using a custom APT
+repository is more time-consuming to set up.
+
+3~ Using #{packages.chroot}# to install custom packages
+
+To install a custom package, simply copy it to the
+#{config/packages.chroot/}# directory. Packages that are inside this
+directory will be automatically installed into the live system during build
+- you do not need to specify them elsewhere.
+
+Packages *{must}* be named in the prescribed way. One simple way to do this
+is to use #{dpkg-name}#.
+
+Using #{packages.chroot}# for installation of custom packages has
+disadvantages:
+
+_* It is not possible to use secure APT.
+
+_* You must install all appropriate packages in the
+#{config/packages.chroot/}# directory.
+
+_* It does not lend itself to storing live system configurations in revision
+control.
+
+3~ Using an APT repository to install custom packages
+
+Unlike using #{packages.chroot}#, when using a custom APT repository you
+must ensure that you specify the packages elsewhere. See {Choosing packages
+to install}#choosing-packages-to-install for details.
+
+While it may seem unnecessary effort to create an APT repository to install
+custom packages, the infrastructure can be easily re-used at a later date to
+offer updates of the modified packages.
+
+3~ Custom packages and APT
+
+live-build uses APT to install all packages into the live system so will
+therefore inherit behaviours from this program. One relevant example is that
+(assuming a default configuration) given a package available in two
+different repositories with different version numbers, APT will elect to
+install the package with the higher version number.
+
+Because of this, you may wish to increment the version number in your custom
+packages' #{debian/changelog}# files to ensure that your modified version is
+installed over one in the official Debian repositories. This may also be
+achieved by altering the live system's APT pinning preferences - see {APT
+pinning}#apt-pinning for more information.
+
+2~ Configuring APT at build time
+
+You can configure APT through a number of options applied only at build
+time. (APT configuration used in the running live system may be configured
+in the normal way for live system contents, that is, by including the
+appropriate configurations through #{config/includes.chroot/}#.) For a
+complete list, look for options starting with #{apt}# in the #{lb_config}#
+man page.
+
+3~choosing-apt-or-aptitude Choosing apt or aptitude
+
+You can elect to use either /{apt}/ or /{aptitude}/ when installing packages
+at build time. Which utility is used is governed by the #{--apt}# argument
+to #{lb config}#. Choose the method implementing the preferred behaviour for
+package installation, the notable difference being how missing packages are
+handled.
+
+_* #{apt}#: With this method, if a missing package is specified, the package
+installation will fail. This is the default setting.
+
+_* #{aptitude}#: With this method, if a missing package is specified, the
+package installation will succeed.
+
+3~ Using a proxy with APT
+
+One commonly required APT configuration is to deal with building an image
+behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}#
+or #{--apt-http-proxy}# options as needed, e.g.
+
+code{
+
+ $ lb config --apt-http-proxy http://proxy/
+
+}code
+
+3~tweaking-apt-to-save-space Tweaking APT to save space
+
+You may find yourself needing to save some space on the image medium, in
+which case one or the other or both of the following options may be of
+interest.
+
+If you don't want to include APT indices in the image, you can omit those
+with:
+
+code{
+
+ $ lb config --apt-indices false
+
+}code
+
+This will not influence the entries in #{/etc/apt/sources.list}#, but merely
+whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is
+that APT needs those indices in order to operate in the live system, so
+before performing #{apt-cache search}# or #{apt-get install}#, for instance,
+the user must #{apt-get update}# first to create those indices.
+
+If you find the installation of recommended packages bloats your image too
+much, provided you are prepared to deal with the consequences discussed
+below, you may disable that default option of APT with:
+
+code{
+
+ $ lb config --apt-recommends false
+
+}code
+
+The most important consequence of turning off recommends is that
+#{live-boot}# and #{live-config}# themselves recommend some packages that
+provide important functionality used by most Live configurations, such as
+#{user-setup}# which #{live-config}# recommends and is used to create the
+live user. In all but the most exceptional circumstances you need to add
+back at least some of these recommends to your package lists or else your
+image will not work as expected, if at all. Look at the recommended packages
+for each of the #{live-*}# packages included in your build and if you are
+not certain you can omit them, add them back into your package lists.
+
+The more general consequence is that if you don't install recommended
+packages for any given package, that is, "packages that would be found
+together with this one in all but unusual installations" (Debian Policy
+Manual, section 7.2), some packages that users of your Live system actually
+need may be omitted. Therefore, we suggest you review the difference turning
+off recommends makes to your packages list (see the #{binary.packages}# file
+generated by #{lb build}#) and re-include in your list any missing packages
+that you still want installed. Alternatively, if you find you only want a
+small number of recommended packages left out, leave recommends enabled and
+set a negative APT pin priority on selected packages to prevent them from
+being installed, as explained in {APT pinning}#apt-pinning.
+
+3~ Passing options to apt or aptitude
+
+If there is not a #{lb config}# option to alter APT's behaviour in the way
+you need, use #{--apt-options}# or #{--aptitude-options}# to pass any
+options through to your configured APT tool. See the man pages for #{apt}#
+and #{aptitude}# for details. Note that both options have default values
+that you will need to retain in addition to any overrides you may
+provide. So, for example, suppose you have included something from
+#{snapshot.debian.org}# for testing purposes and want to specify
+#{Acquire::Check-Valid-Until=false}# to make APT happy with the stale
+#{Release}# file, you would do so as per the following example, appending
+the new option after the default value #{--yes}#:
+
+code{
+
+ $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false"
+
+}code
+
+Please check the man pages to fully understand these options and when to use
+them. This is an example only and should not be construed as advice to
+configure your image this way. This option would not be appropriate for,
+say, a final release of a live image.
+
+For more complicated APT configurations involving #{apt.conf}# options you
+might want to create a #{config/apt/apt.conf}# file instead. See also the
+other #{apt-*}# options for a few convenient shortcuts for frequently needed
+options.
+
+3~apt-pinning APT pinning
+
+For background, please first read the #{apt_preferences(5)}# man page. APT
+pinning can be configured either for build time, or else for run time. For
+the former, create #{config/archives/*.pref}#,
+#{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the
+latter, create #{config/includes.chroot/etc/apt/preferences}#.
+
+Let's say you are building a ${testing} live system but need all the live
+packages that end up in the binary image to be installed from sid at build
+time. You need to add sid to your APT sources and pin the live packages from
+it higher, but all other packages from it lower, than the default
+priority. Thus, only the packages you want are installed from sid at build
+time and all others are taken from the target system distribution,
+${testing}. The following will accomplish this:
+
+code{
+
+ $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot
+ $ cat >> config/archives/sid.pref.chroot << EOF
+ Package: live-*
+ Pin: release n=sid
+ Pin-Priority: 600
+
+ Package: *
+ Pin: release n=sid
+ Pin-Priority: 1
+ EOF
+
+}code
+
+Negative pin priorities will prevent a package from being installed, as in
+the case where you do not want a package that is recommended by another
+package. Suppose you are building an LXDE image using #{task-lxde-desktop}#
+in #{config/package-lists/desktop.list.chroot}#, but don't want the user
+prompted to store wifi passwords in the keyring. This metapackage depends on
+/{lxde-core}/, which recommends /{gksu}/, which in turn recommends
+/{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/
+package. This can be done by adding the following stanza to
+#{config/apt/preferences}#:
+
+code{
+
+ Package: gnome-keyring
+ Pin: version *
+ Pin-Priority: -1
+
+}code