Provided by: schroot_1.4.25-1_i386 bug

NAME

       schroot - frequently asked questions

DESCRIPTION

       This  manual  page  covers  various  frequently  asked  questions about
       configuration and usage of schroot.

CONFIGURATION

   Why is schroot overwriting configuration files in the chroot?
       By default, schroot copies over the  system  NSS  databases  ('passwd',
       'shadow',  'group', 'gshadow', 'services', 'protocols', 'networks', and
       'hosts', etc.) into the chroot.  The reason for this is that the chroot
       environment  is  not  a completely separate system, and it copying them
       over keeps them synchronised.  However, this is not  always  desirable,
       particularly if installing a package in the chroot creates system users
       and groups which  are  not  present  on  the  host,  since  these  will
       disappear next time the databases are copied over.

       The  suggested workaround here is to disable the copying by removing or
       commenting out the databases in the NSSDATABASES file  in  the  script-
       config       file       for       the      chroot.       These      are
       /etc/schroot/default/nssdatabases  and  /etc/schroot/default/config  by
       default.

       In  the  future,  we will be working on a better scheme for keeping the
       host and chroot databases in sync which can merge entries  rather  than
       overwriting  the  entire database, which would preserve chroot-specific
       changes.

   Should I use the plain or directory chroot type?
       These two chroot types are basically equivalent, since  they  are  both
       just  directories in the filesystem.  plain is very simple and does not
       perform any setup tasks; the only reason you would want to use it is if
       you're  upgrading  from a program such as dchroot(1) or chroot(8) which
       don't do anything other than running a command or shell in a directory.
       On  the  other  hand, directory chroots do run setup scripts, which can
       mount additional filesystems and do other setup tasks.

ADVANCED CONFIGURATION

   What are snapshots and unions?
       Some chroot types  support  cloning.   This  means  when  you  start  a
       session, you get a copy of the chroot which lasts just for the lifetime
       of the session.  This is useful when you want a temporary clean copy of
       a  system  for  a single task, which is then automatically deleted when
       you're done with it.  For example, the Debian package build daemons run
       sbuild(1)  to  build  Debian packages, and this program uses schroot to
       create  a  clean  build  environment   for   each   package.    Without
       snapshotting, the chroot would need to be reset to its initial state at
       the end of each build to make it ready for the next one, and any debris
       left  over from package removals or earlier builds could interfere with
       the next build.

       The most commonly-used snapshotting method  is  to  use  LVM  snapshots
       (chroot type 'lvm-snapshot').  In this case the chroot must exist on an
       LVM logical volume (LV); snapshots of an  LV  may  then  be  made  with
       lvcreate(8)  during  chroot session setup.  However, these use up a lot
       of disk space.  A newer method is to use Btrfs snapshots which  use  up
       much  less  disk  space (chroot type 'btrfs-snapshot'), and may be more
       reliable than LVM snapshots.  Btrfs is however still experimental,  but
       it is hoped that it will become the recommended method as it matures.

       Unions  are an alternative to snapshots.  In this situation, instead of
       creating a copy of the  chroot  filesystem,  we  overlay  a  read-write
       temporary  filesystem  on  top  of  the  chroot  filesystem so that any
       modifications are stored in the overlay, leaving  the  original  chroot
       filesystem  untouched.   The  Linux kernel has yet to integrate support
       for union filesystems such as aufs and unionfs, so  LVM  snapshots  are
       still the recommended method at present.

USAGE

   Can I run a daemons in a chroot?
       A  common  problem  is  trying to run a daemon in a chroot, and finding
       that this doesn't work.  Typically, the daemon is killed shortly  after
       it starts up.

       When  schroot  runs, it begins a session, runs the specified command or
       shell, waits for the command or shell to exit, and  then  it  ends  the
       session.   For  a  normal  command  or  shell,  this  works  just fine.
       However, daemons normally start up by running  in  the  background  and
       detaching from the controlling terminal.  They do this by forking twice
       and letting the  parent  processes  exit.   Unfortunately,  this  means
       schroot  detects  that  the  program  exited  (the daemon is a orphaned
       grandchild of this process) and it then  ends  the  session.   Part  of
       ending  the session is killing all processes running inside the chroot,
       which means the daemon is killed as the session ends.

       In consequence, it's  not  possible  to  run  a  daemon  directly  with
       schroot.   You  can  however  do  it  if  you  create  a  session  with
       --begin-session and then run the daemon with --run-session.  It's  your
       responsibility  to  end  the session with --end-session when the daemon
       has terminated or you no longer need it.

   How do I manually cleaning up a broken session?
       Occasionally, it may be necessary to manually clean  up  sessions.   If
       something changes on your system which causes the setup scripts to fail
       when ending a  session,  for  example  removal  of  a  needed  file  or
       directory,  it  may  not be possible for schroot to clean everything up
       automatically.  For each of  the  session  directories  listed  in  the
       "Session directories" section in schroot(1), any files with the name of
       the session ID need deleting, and any directories with the name of  the
       session  ID  need umounting (if there are any filesystems mounted under
       it), and then also removing.

       For example, to remove a session named my-session by hand:

       o      Remove the session configuration file
              % rm /var/lib/schroot/session/my-session_|

       +o      Check for mounted filesystems
              % /usr/lib/i386-linux-
              gnu/schroot/schroot-listmounts -m /var/lib/schroot/mount/my-session_|

       +o      Unmount any mounted filesystems

       o      Remove /var/lib/schroot/mount/my-session

       o      Repeat     for     the     other     directories     such     as
              /var/lib/schroot/union/underlay,  /var/lib/schroot/union/overlay
              and /var/lib/schroot/unpack

       NOTE: Do not remove any directories without checking if there  are  any
       filesystems  mounted  below them, since filesystems such as /home could
       still be bind mounted.  Doing so could cause irretrievable data loss!

ADVANCED USAGE

   How do I use sessions?
       In normal use, running a command might look like this:
       % schroot -c squeeze -- command_|

       which would run the command command in the squeeze chroot.  While  it's
       not  apparent  that  a  session is being used here, schroot is actually
       doing the following steps:

       o      Creating a session using  the  squeeze  chroot.   This  will  be
              automatically     given     a     unique     name,    such    as
              squeeze-57a69547-e014-4f5d-a98b-f4f35a005307, though  you  don't
              usually need to know about this

       o      Setup scripts are run to create the session chroot and configure
              it for you

       o      The command command is run inside the session chroot

       o      Setup scripts are run to clean up the session chroot

       o      The session is deleted

       Now, if you wanted to run more than one command, you could run a  shell
       and run them interactively, or you could put them into shell script and
       run that instead.  But you might want to do something in between,  such
       as  running arbitrary commands from a program or script where you don't
       know which commands to run in advance.  You might also want to  preseve
       the  chroot  state  in  between  commands,  where  the normal automatic
       session creation would reset the state in between each  command.   This
       is  what  sessions are for: once created, the session is persistent and
       won't be automatically removed.  With a session, you can  run  as  many
       commands  as you like, but you need to create and delete the session by
       hand since schroot can't know by itself when you're done with it unlike
       in the single command case above.  This is quite easy:
       % schroot --begin-session -c squeeze_|
       squeeze-57a69547-e014-4f5d-a98b-f4f35a005307

       This  created  a new session based upon the squeeze chroot.  The unique
       name for the session, the session ID, was printed to  standard  output,
       so we could also save it as a shell variable at the same time like so:
       % SESSION=$(schroot --begin-session -c squeeze)_|
       % echo $SESSION_|
       squeeze-57a69547-e014-4f5d-a98b-f4f35a005307

       Now  we  have  created  the  session and got the session ID, we can run
       commands in it using the session ID:
       % schroot --run-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
       -- command1_|

       or
       % schroot --run-session -c "$SESSION" -- command1_|

       and then as many more commands as we like
       % schroot --run-session -c "$SESSION" -- command2_|
       % schroot --run-session -c "$SESSION" -- command3_|
       % schroot --run-session -c "$SESSION" -- command4_|

       etc.

       When we are done with the session, we can remove it with --end-session:
       %                schroot                --end-session                -c
       squeeze-57a69547-e014-4f5d-a98b-f4f35a005307_|

       or
       % schroot --end-session -c $SESSION_|

       Since the  automatically  generated  session  names  can  be  long  and
       unwieldy, the --session-name option allows you to provide you own name:

       % schroot --begin-session -c squeeze --session-name my-name_|
       my-name

CONTRIBUTING

   Getting help and getting involved
       The  mailing  list <buildd-tools-devel@lists.alioth.debian.org> is used
       for both user support and development  discussion.   The  list  may  be
       subscribed      to      from      the      project      website      at
       https://alioth.debian.org/projects/buildd-tools/ or  the  Mailman  list
       interface   at  http://lists.alioth.debian.org/mailman/listinfo/buildd-
       tools-devel.

   Reporting bugs
       On Debian systems, bugs may be reported using the reportbug(1) tool, or
       alternatively      by     mailing     <submit@bugs.debian.org>     (see
       http://bugs.debian.org for details on how to do that).

   Getting the latest sources
       schroot is maintained in the git version control system.  You  can  get
       the latest sources from git://git.debian.org/git/buildd-tools/schroot.
       % git clone git://git.debian.org/git/buildd-tools/schroot_|

       The  master  branch  containes the current development release.  Stable
       releases are found on branches, for example the 1.4 series of  releases
       are on the schroot-1.4 branch.

AUTHORS

       Roger Leigh.

COPYRIGHT

       Copyright (C) 2005-2011  Roger Leigh <rleigh@debian.org>

       schroot  is  free  software:  you  can redistribute it and/or modify it
       under the terms of the GNU General Public License as published  by  the
       Free  Software Foundation, either version 3 of the License, or (at your
       option) any later version.

SEE ALSO

       dchroot(1), schroot(1), sbuild(1), schroot-setup(5), schroot.conf(5).