Provided by: schroot_1.6.10-1ubuntu3_amd64 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.  This may be achieved by  setting
       the  setup.nssdatabases  key to be empty in schroot.conf.  In prior schroot releases, this
       was   done   by   commenting    out    the    NSSDATABASES    file    for    the    chroot
       (/etc/schroot/default/config  by  default).   The  database list may also be customised by
       editing the  file  containing  the  database  list  (/etc/schroot/default/nssdatabases  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/x86_64-linux-gnu/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-2012  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).