Provided by: schroot_1.4.17-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 dæmons  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 dæmons in a chroot?
       A common problem is trying to run a dæmon in a chroot, and finding that
       this doesn't work.  Typically, the dæmon 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, dæmons 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  dæmon 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 dæmon is killed as the session ends.

       In consequence, it's not possible to run a dæmon directly with schroot.
       You  can however do it if you create a session with --begin-session and
       then run the dæmon 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:

       ·      Remove the session configuration file
              % rm /var/lib/schroot/session/my-session·      Check for mounted filesystems
              % /usr/lib/schroot/schroot-listmounts -m /var/lib/schroot/mount/my-session·      Unmount any mounted filesystems

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

       ·      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:

       ·      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

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

       ·      The command command is run inside the session chroot

       ·      Setup scripts are run to clean up the session chroot

       ·      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 © 2005-2010  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).