1SCHROOT.CONF(5)                  Debian sbuild                 SCHROOT.CONF(5)
2
3
4

NAME

6       schroot.conf - chroot definition file for schroot
7

DESCRIPTION

9       schroot.conf  is a plain UTF-8 text file, describing the chroots avail‐
10       able for use with schroot.
11
12       Comments are introduced following  a  ‘#’  (“hash”)  character  at  the
13       beginning  of  a  line, or following any other text.  All text right of
14       the ‘#’ is treated as a comment.
15
16       The configuration format is an INI-style format, split into  groups  of
17       key-value pairs separated by section names in square brackets.
18
19   General options
20       A  chroot is defined as a group of key-value pairs, which is started by
21       a name in square brackets on a line by itself.  The  file  may  contain
22       multiple groups which therefore define multiple chroots.
23
24       A  chroot  definition  is  started  by the name of the chroot in square
25       brackets.  For example,
26
27              [sid]
28
29       The name is  subject  to  certain  naming  restrictions.   For  further
30       details, see the section “Chroot Names” below.
31
32       This is then followed by several key-value pairs, one per line:
33
34       type=type
35              The  type  of the chroot.  Valid types are ‘plain’, ‘directory’,
36              ‘file’,   ‘loopback’,   ‘block-device’,   ‘btrfs-snapshot’   and
37              ‘lvm-snapshot’.   If  empty  or  omitted,  the  default  type is
38              ‘plain’.  Note that ‘plain’ chroots do not run setup scripts and
39              mount  filesystems;  ‘directory’  is  recommended for normal use
40              (see “Plain and directory chroots”, below).
41
42       description=description
43              A short description of the chroot.  This may  be  localised  for
44              different languages; see the section “Localisation” below.
45
46       priority=number
47              Set  the  priority  of  a  chroot.  number is a positive integer
48              indicating whether a distribution is older  than  another.   For
49              example,  “oldstable”  and  “oldstable-security”  might  be ‘0’,
50              while “stable” and “stable-security” are ‘1’, “testing”  is  ‘2’
51              and  “unstable”  is  ‘3’.  The values are not important, but the
52              difference between them is.  This option is  deprecated  and  no
53              longer  used  by  schroot, but is still permitted to be used; it
54              will be obsoleted and removed in a future release.
55
56       message-verbosity=verbosity
57              Set the verbosity of messages printed by  schroot  when  setting
58              up, running commands and cleaning up the chroot.  Valid settings
59              are ‘quiet’ (suppress most messages), ‘normal’ (the default) and
60              ‘verbose’  (show  all  messages).  This setting is overridden by
61              the options --quiet and --verbose.
62
63       users=user1,user2,...
64              A comma-separated list of users which are allowed access to  the
65              chroot.   If  empty  or omitted, no users will be allowed access
66              (unless a group they belong to is also specified in groups).
67
68       groups=group1,group2,...
69              A comma-separated list of groups which are allowed access to the
70              chroot.  If empty or omitted, no groups of users will be allowed
71              access.
72
73       root-users=user1,user2,...
74              A comma-separated list of users which are allowed  password-less
75              root  access  to the chroot.  If empty or omitted, no users will
76              be allowed root access without a password (but if a  user  or  a
77              group  they  belong to is in users or groups, respectively, they
78              may gain access with a password).  See  the  section  “Security
79              below.
80
81       root-groups=group1,group2,...
82              A comma-separated list of groups which are allowed password-less
83              root access to the chroot.  If empty or omitted, no  users  will
84              be  allowed  root  access without a password (but if a user or a
85              group they belong to is in users or groups,  respectively,  they
86              may  gain  access  with a password).  See the section “Security
87              below.
88
89       aliases=alias1,alias2,...
90              A comma-separated list of aliases  (alternate  names)  for  this
91              chroot.  For example, a chroot named “sid” might have an ‘unsta‐
92              ble’ alias for convenience.  Aliases are  subject  to  the  same
93              naming restrictions as the chroot name itself.
94
95       profile=directory
96
97       script-config=filename
98              The behaviour of the chroot setup scripts may be customised on a
99              per-chroot basis by setting a  specific  configuration  profile.
100              The  directory  is  relative  to  /etc/schroot.   The default is
101              ‘default’.  The files in this directory are sourced by the setup
102              scripts,  and  so their behaviour may be customised by selecting
103              the appropriate profile.  Alternatives  are  ‘minimal’  (minimal
104              configuration),  ‘desktop’  (for running desktop applications in
105              the chroot, making  more  functionality  from  the  host  system
106              available  in the chroot) and ‘sbuild’ (for using the chroot for
107              Debian package building).  Other packages may provide additional
108              profiles.   The  default  values  of the keys setup.config, set‐
109              up.copyfiles, setup.fstab and setup.nssdatabases are  set  based
110              upon the profile setting.
111
112              Note  that the profile key replaces the older script-config key.
113              The script-config key is exactly the same as  profile,  but  has
114/config” appended to it.  The default filename is ‘default/con‐
115              fig’.  Either of these keys may be used.  If both  are  present,
116              then script-config will take precedence (profile will be unset).
117              script-config is deprecated and will  be  removed  in  a  future
118              release.   Note  that  profile is equivalent to script-config if
119              the file sourced by script-config  only  contains  the  standard
120              variables  provided  by  schroot; if any additional variables or
121              shell script fragments have been added,  please  also  set  set‐
122              up.config, which will continue to allow this file to be sourced.
123              It is recommended to replace the use of the  sourced  file  with
124              additional keys in schroot.conf where possible, but it will con‐
125              tinue to be possible to source an additional configuration  file
126              using setup.config.
127
128              Desktop users should note that the fstab file desktop/fstab will
129              need editing if you use gdm3; please see the  comments  in  this
130              file  for  further  instructions.   The preserve-environment key
131              should also be set to ‘true’ so that  the  environment  is  pre‐
132              served inside the chroot.
133
134              If  none  of the configuration profiles provided above meet your
135              needs, then they may be edited to further customise them, and/or
136              copied and used as a template for entirely new profiles.
137
138              Note  that the different profiles have different security impli‐
139              cations; see the section “Security” below for further details.
140
141       setup.config=filename
142              This key specifies a file which the setup  scripts  will  source
143              when  they  are  run.  This defaults to the same value as set by
144              script-config.  The file is a Bourne shell script, and in conse‐
145              quence  may  contain any valid shell code, in addition to simple
146              variable assignments.  This will, for example,  allow  behaviour
147              to  be customised according to the specific chroot type or name.
148              Note that the script will be sourced once  for  each  and  every
149              script invocation, and must be idempotent.
150
151              All  the  default  settings  in this file are now settable using
152              configuration keys in schroot.conf, as detailed below.  Existing
153              configuration  should  be modified to use these keys in place of
154              this file.  See schroot-script-config(5)  for  further  details.
155              This  type  of setup script configuration file is no longer pro‐
156              vided as part of the standard profiles, but will continue to  be
157              sourced if present and this key is set.
158
159       setup.copyfiles=filename
160              A  file  containing a list of files to copy into the chroot (one
161              file per line).  The file will have the same  absolute  location
162              inside the chroot.
163
164       setup.fstab=filename
165              The filesystem table file to be used to mount filesystems within
166              the chroot.  The  format  of  this  file  is  the  same  as  for
167              /etc/fstab, documented in fstab(5).  The only difference is that
168              the mountpoint path fs_dir is relative  to  the  chroot,  rather
169              than  the root.  Also note that mountpoints are canonicalised on
170              the host, which will ensure that absolute symlinks point  inside
171              the  chroot,  but complex paths containing multiple symlinks may
172              be resolved incorrectly; it is inadvisable to  use  nested  sym‐
173              links as mountpoints.
174
175       setup.nssdatabases=filename
176              A  file  listing  the  system databases to copy into the chroot.
177              The  default  databases  are  ‘passwd’,  ‘shadow’,  ‘group’  and
178              ‘gshadow’.   Other  potential  databases  which  could  be added
179              include ‘services’, ‘protocols’, ‘networks’, and  ‘hosts’.   The
180              databases  are  copied  using  getent(1) so all database sources
181              listed in /etc/nsswitch.conf will be used for each database.
182
183       setup.services=service1,service2,...
184              A comma-separated list of services to run in the chroot.   These
185              will  be  started  when the session is started, and stopped when
186              the session is ended.
187
188       command-prefix=command,option1,option2,...
189              A comma-separated list of a command and the options for the com‐
190              mand.  This command and its options will be prefixed to all com‐
191              mands run inside the chroot.  This is useful for adding commands
192              such  as  nice,  ionice or eatmydata for all commands run inside
193              the chroot.  nice and ionice will affect CPU and I/O scheduling.
194              eatmydata ingores filesystem fsync operations, and is useful for
195              throwaway snapshot chroots where you don't care about  dataloss,
196              but do care about high speed.
197
198       personality=persona
199              Set  the  personality  (process  execution domain) to use.  This
200              option is useful when using a 32-bit chroot  on  64-bit  system,
201              for   example.   Valid  options  on  Linux  are  ‘bsd’,  ‘hpux’,
202              ‘irix32’,  ‘irix64’,  ‘irixn32’,  ‘iscr4’,  ‘linux’,  ‘linux32’,
203              ‘linux_32bit’,  ‘osf4’,  ‘osr5’, ‘riscos’, ‘scorvr3’, ‘solaris’,
204              ‘sunos’, ‘svr4’, ‘uw7’, ‘wysev386’, and  ‘xenix’.   The  default
205              value  is ‘linux’.  There is also the special option ‘undefined’
206              (personality not set).  For a 32-bit chroot on a 64-bit  system,
207              ‘linux32’  is  the  option  required.  The only valid option for
208              non-Linux systems is ‘undefined’.  The default  value  for  non-
209              Linux systems is ‘undefined’.
210
211       preserve-environment=true|false
212              By  default,  the  environment  will not be preserved inside the
213              chroot, instead a minimal environment will be used.  Set to true
214              to  always preserve the environment.  This is useful for example
215              when running X applications inside the chroot,  which  need  the
216              environment  to function correctly.  The environment may also be
217              preserved using the --preserve-environment option.
218
219       shell=shell
220              When running a login shell a number of potential shells will  be
221              considered,  in this order: the command in the SHELL environment
222              variable (if --preserve-environment is used,  or  preserve-envi‐
223              ronment  is enabled), the user's shell in the ‘passwd’ database,
224              /bin/bash and finally  /bin/sh.   This  setting  overrides  this
225              list,  and  will  use the shell specified.  It may be overridden
226              using the --shell option.
227
228       environment-filter=regex
229              The environment to be set in the  chroot  will  be  filtered  in
230              order  to remove environment variables which may pose a security
231              risk.  Any environment variable  matching  the  specified  POSIX
232              extended  regular  expression will be removed prior to executing
233              any command in the chroot.
234
235              Potentially dangerous  environment  variables  are  removed  for
236              safety by default using the following regular expression:
237              “^(BASH_ENV|CDPATH|ENV|HOSTALIASES|IFS|KRB5_CONFIG|KRBCONFDIR
238              |KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMAIN|NLSPATH|PATH_LOCALE
239              |RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TERMPATH)$”.
240
241   Plain and directory chroots
242       Chroots of type ‘plain’ or ‘directory’ are  directories  accessible  in
243       the  filesystem.  The two types are equivalent except for the fact that
244       directory chroots run setup scripts, whereas plain chroots do not.   In
245       consequence,  filesystems  such  as  /proc  are  not  mounted  in plain
246       chroots; it is the responsibility of the system administrator  to  con‐
247       figure  such  chroots  by hand, whereas directory chroots are automati‐
248       cally  configured.   Additionally,  directory  chroots  implement   the
249       filesystem union chroot options (see “Filesystem Union chroot options”,
250       below).
251
252       These chroot types have an additional (mandatory) configuration option:
253
254       directory=directory
255              The directory containing the chroot environment.  This is  where
256              the  root  will  be changed to when executing a login shell or a
257              command.  The directory must exist and  have  read  and  execute
258              permissions  to  allow  users  access to it.  Note that on Linux
259              systems it will be bind-mounted elsewhere for use as  a  chroot;
260              the  directory  for  ‘plain’ chroots is mounted with the --rbind
261              option to mount(8), while for ‘directory’ chroots --bind is used
262              instead so that sub-mounts are not preserved (they should be set
263              in the fstab file just like in /etc/fstab on the host).
264
265   File chroots
266       Chroots of type ‘file’ are files on the current  filesystem  containing
267       an  archive  of  the  chroot  files.   They implement the source chroot
268       options (see “Source chroot options”, below).  Note that a  correspond‐
269       ing  source  chroot (of type ‘file’) will be created for each chroot of
270       this type; this is for convenient access to the  source  archive,  e.g.
271       for  the  purpose of updating. These additional options are also imple‐
272       mented:
273
274       file=filename
275              The file containing the archived chroot environment (mandatory).
276              This  must  be  a tar (tape archive), optionally compressed with
277              gzip, bzip2, xz, lzop or  lz4.   The  file  extensions  used  to
278              determine  the  type  are  are .tar, .tar.gz, .tar.bz2, .tar.xz,
279              .tar.lzop, .tar.lz4, .tgz, .tbz, .txz,  .tzo  and  .tlz4.   This
280              file  must  be  owned  by  the root user, and not be writable by
281              other.  Note that zip archives are no longer supported; zip  was
282              not  able  to  archive  named pipes and device nodes, so was not
283              suitable for archiving chroots.
284
285       location=path
286              This is the path to the chroot inside the archive.  For example,
287              if  the archive contains a chroot in /squeeze, you would specify
288              “/squeeze” here.  If the chroot is the only  thing  in  the  ar‐
289              chive, i.e. / is the root filesystem for the chroot, this option
290              should be left blank, or omitted entirely.
291
292   Loopback chroots
293       Chroots of type ‘loopback’ are a filesystem  available  as  a  file  on
294       disk, accessed via a loopback mount.  The file will be loopback mounted
295       and unmounted on demand.   Loopback  chroots  implement  the  mountable
296       chroot  and  filesystem  union  chroot  options  (see “Mountable chroot
297       options” and “Filesystem Union chroot options”, below), plus  an  addi‐
298       tional option:
299
300       file=filename
301              This  is  the  filename  of  the file containing the filesystem,
302              including the absolute path.  For example “/srv/chroot/sid”.
303
304   Block device chroots
305       Chroots of  type  ‘block-device’  are  a  filesystem  available  on  an
306       unmounted  block  device.   The device will be mounted and unmounted on
307       demand.  Block  device  chroots  implement  the  mountable  chroot  and
308       filesystem  union  chroot  options  (see “Mountable chroot options” and
309Filesystem Union chroot options”, below), plus an additional option:
310
311       device=device
312              This is the device name of the block device, including the abso‐
313              lute path.  For example, “/dev/sda5”.
314
315   Btrfs snapshot chroots
316       Chroots  of  type ‘btrfs-snapshot’ are a Btrfs snapshot created from an
317       existing Btrfs subvolume on a mounted  Btrfs  filesystem.   A  snapshot
318       will  be created from this source subvolume on demand at the start of a
319       session, and then the snapshot will be mounted.  At the end of the ses‐
320       sion,  the  snapshot  will  be unmounted and deleted.  This chroot type
321       implements the source chroot  options  (see  “Source  chroot  options”,
322       below).   Note that a corresponding source chroot (of type ‘directory’)
323       will be created for each chroot of this type; this  is  for  convenient
324       access  to  the source volume. These additional options are also imple‐
325       mented:
326
327       btrfs-source-subvolume=directory
328              The directory containing the source subvolume.
329
330       btrfs-snapshot-directory=directory
331              The directory in which to  store  the  snapshots  of  the  above
332              source subvolume.
333
334   LVM snapshot chroots
335       Chroots  of  type  ‘lvm-snapshot’  are a filesystem available on an LVM
336       logical volume (LV).  A snapshot LV will be created  from  this  LV  on
337       demand,  and then the snapshot will be mounted.  At the end of the ses‐
338       sion, the snapshot LV will be unmounted and removed.
339
340       LVM snapshot chroots implement the source chroot options  (see  “Source
341       chroot  options”, below), and all the options for ‘block-device’.  Note
342       that a corresponding source chroot (of  type  ‘block-device’)  will  be
343       created  for each chroot of this type; this is for convenient access to
344       the source device. This additional option is also implemented:
345
346       lvm-snapshot-options=snapshot_options
347              Snapshot options.  These  are  additional  options  to  pass  to
348              lvcreate(8).  For example, “-L 2g” to create a snapshot 2 GiB in
349              size.  Note: the LV name (-n), the snapshot option (-s) and  the
350              original LV path may not be specfied here; they are set automat‐
351              ically by schroot.
352
353   Custom chroots
354       Chroots of type ‘custom’ are a special type of chroot, used for  imple‐
355       menting  new  types  of chroot not supported by any of the above chroot
356       types.  This may be useful for implementing and testing  a  new  chroot
357       type  without needing to write any C++ code.  However, you will need to
358       write your own setup script to do the setup work, since by itself  this
359       chroot type does very little.  You will also need to add custom keys to
360       your chroot definition for use in the setup script; unlike the configu‐
361       ration  for  the  above chroot types, no validation of the options will
362       take place unless you do it  yourself  in  your  custom  setup  script.
363       These additional options are also implemented:
364
365       custom-session-cloneable=true|false
366              Set  whether  or  not  sessions  may be cloned using this chroot
367              (enabled by default).
368
369       custom-session-purgeable=true|false
370              Set whether or not sessions may  be  cloned  using  this  chroot
371              (disabled by default).
372
373       custom-source-cloneable=true|false
374              Set  whether  or  not  source  chroots  may be cloned using this
375              chroot (disabled by default).
376
377   Source chroot options
378       The ‘btrfs-snapshot’, ‘file’ and ‘lvm-snapshot’ chroot types  implement
379       source  chroots.  Additionally, chroot types with union support enabled
380       implement  source  chroots  (see  “Filesystem  Union  chroot  options”,
381       below).   These  are chroots which automatically create a copy of them‐
382       selves before use, and are  usually  session  managed.   These  chroots
383       additionally provide an extra chroot in the source: namespace, to allow
384       convenient access to the original (non-snapshotted) data, and to aid in
385       chroot  maintenance.  I.e. for a chroot named wheezy (chroot:wheezy), a
386       corresponding source:wheezy chroot will be created.  For  compatibility
387       with  older  versions  of  schroot  which did not support namespaces, a
388       chroot with a -source suffix appended to the chroot name will  be  cre‐
389       ated  in  addition  (i.e. wheezy-source using the above example).  Note
390       that these compatibility names will be removed in schroot 1.5.0, so the
391       use  of  the source: namespace is preferred over the use of the -source
392       suffix form.  See schroot(1) for further details.
393
394       These chroots provide the following additional options:
395
396       source-clone=true|false
397              Set whether the source chroot  should  be  automatically  cloned
398              (created) for this chroot.  The default is true to automatically
399              clone, but if desired may be disabled by setting to  false.   If
400              disabled, the source chroot will be inaccessible.
401
402       source-users=user1,user2,...
403              A  comma-separated list of users which are allowed access to the
404              source chroot.  If empty or omitted, no users  will  be  allowed
405              access.  This will become the users option in the source chroot.
406
407       source-groups=group1,group2,...
408              A comma-separated list of groups which are allowed access to the
409              source chroot.  If empty or omitted, no users  will  be  allowed
410              access.   This  will  become  the  groups  option  in the source
411              chroot.
412
413       source-root-users=user1,user2,...
414              A comma-separated list of users which are allowed  password-less
415              root access to the source chroot.  If empty or omitted, no users
416              will be allowed root access without a password (but if a user is
417              in  users,  they  may  gain  access with a password).  This will
418              become the root-users option in the source chroot.  See the sec‐
419              tion “Security” below.
420
421       source-root-groups=group1,group2,...
422              A comma-separated list of groups which are allowed password-less
423              root access to the source chroot.  If empty or omitted, no users
424              will  be allowed root access without a password (but if a user's
425              group is in groups, they may gain access with a password).  This
426              will  become  the  root-groups option in the source chroot.  See
427              the section “Security” below.
428
429   Mountable chroot options
430       The ‘block-device’, ‘loopback’ and ‘lvm-snapshot’ chroot  types  imple‐
431       ment  device mounting.  These are chroots which require the mounting of
432       a device in order to access the chroot.  These chroots provide the fol‐
433       lowing additional options:
434
435       mount-options=options
436              Mount  options  for  the  block  device.   These  are additional
437              options   to   pass   to    mount(8).     For    example,    “-o
438              atime,sync,user_xattr”.
439
440       location=path
441              This  is  the  path  to  the chroot inside the filesystem on the
442              device.  For example, if the filesystem  contains  a  chroot  in
443              /chroot/sid,  you  would  specify  “/chroot/sid”  here.   If the
444              chroot is the only thing on the filesystem, i.e. / is  the  root
445              filesystem  for the chroot, this option should be left blank, or
446              omitted entirely.
447
448   Filesystem Union chroot options
449       The ‘block-device’, ‘directory’ and ‘loopback’ chroot types  allow  for
450       the creation of a session using filesystem unions to overlay the origi‐
451       nal filesystem  with  a  separate  writable  directory.   The  original
452       filesystem  is read-only, with any modifications made to the filesystem
453       made in the overlying writable directory, leaving the original filesys‐
454       tem  unchanged.   A  union permits multiple sessions to access and make
455       changes to a single chroot simultaneously, while  keeping  the  changes
456       private to each session.  To enable this feature, set union-type to any
457       supported value.  If enabled, the chroot will also be a source  chroot,
458       which  will  provide  additional  options (see “Source chroot options”,
459       above).  All entries are optional.
460
461       union-type=type
462              Set the union filesystem type.  Currently supported  filesystems
463              are  ‘aufs’,  ‘overlayfs’,  ‘overlay’  (as  of  Linux  4.0+) and
464              ‘unionfs’.  The default is ‘none’, which disables this feature.
465
466       union-mount-options=options
467              Union filesystem mount options (branch configuration), used  for
468              mounting  the  union filesystem specified with union-type.  This
469              replaces the complete “-o” string for mount and allows  for  the
470              creation of complex filesystem unions.  Note that ‘aufs’, ‘over‐
471              layfs’  and  ‘unionfs’  each  have  different  supported   mount
472              options.   Note: One can use the variables “${CHROOT_UNION_OVER‐
473              LAY_DIRECTORY}”  and   “${CHROOT_UNION_UNDERLAY_DIRECTORY}”   to
474              refer  to  the  writable overlay session directory and read-only
475              underlying directory which are to  form  the  union.   See  sch‐
476              root-setup(5) for a complete variable list.
477
478       union-overlay-directory=directory
479              Specify the directory where the writeable overlay session direc‐
480              tories  will  be  created.   The   default   is   ‘/var/lib/sch‐
481              root/union/overlay’.
482
483       union-underlay-directory=directory
484              Specify the directory where the read-only underlying directories
485              will be created.  The default is  ‘/var/lib/schroot/union/under‐
486              lay’.
487
488   Customisation
489       In  addition  to the configuration keys listed above, it is possible to
490       add custom keys.  These keys will be used to add additional environment
491       variables  to  the setup script environment when setup scripts are run.
492       The only restriction is that the key name consists only of alphanumeric
493       characters  and hyphens, begins with an alphabet character and contains
494       at least one period.  That is to say, that it matches the extended reg‐
495       ular expression “^([a-z][a-z0-9]*\.)+[a-z][a-z0-9-]*$”.
496
497       For example:
498              debian.apt-update=true
499              debian.distribution=unstable
500
501       would set the following environment:
502              DEBIAN_APT_UPDATE=true
503              DEBIAN_DISTRIBUTION=unstable
504
505       Note that it is an error to use different key names which would set the
506       same environment variable by mixing periods and hyphens.
507
508       Custom configuration keys may also be modified  at  runtime  using  the
509       --option option.  However, for security, only selected keys may be mod‐
510       ified.  These keys are specified using the following options:
511
512       user-modifiable-keys=key1,key2,..
513              Set the keys which users may modify using --option.
514
515       root-modifiable-keys=key1,key2,.. Set the keys which the
516              root user may modify using --option.  Note that  the  root  user
517              may  use  the keys specified in user-modifiable-keys in addition
518              to those specified here.
519
520   Localisation
521       Some keys may be localised in multiple languages.  This is achieved  by
522       adding  the  locale  name  in  square brackets after the key name.  For
523       example:
524              description[en_GB]=British English translation
525
526       This will localise the description key for the en_GB locale.
527              description[fr]=French translation
528
529       This will localise the description key for all French locales.
530

CHROOT NAMES

532       A number of characters or words are not permitted  in  a  chroot  name,
533       session  name  or  configuration  filename.  The name may not contain a
534       leading period (‘.’).  The characters ‘:’ (colon), ‘,’ (comma) and  ‘/’
535       (forward  slash)  are not permitted anywhere in the name.  The name may
536       also not contain a trailing  tilde  (‘~’).   The  rationale  for  these
537       restrictions is given below.
538
539.’    A  leading period could be used to create a name with a relative
540              path in it, in combination with ‘/’, and this could allow  over‐
541              writing  of  files  on  the  host filesystem.  Not allowing this
542              character also means hidden files cannot be  created.   It  also
543              means  some  editor  backups are automatically ignored.  Periods
544              are allowed anywhere else in the name.
545
546:’    A colon is used as a namespace delimiter, and so is not  permit‐
547              ted as part of a chroot or session name.  LVM snapshot names may
548              also not contain this character due to a naming  restriction  by
549              lvcreate(8).
550
551/’    Names containing this character are not valid filenames.  A for‐
552              ward slash would potentially allow creation of files  in  subdi‐
553              rectories.
554
555,’    Commas  are  used to separate items in lists.  Aliases are sepa‐
556              rated by commas and hence can't contain commas in their name.
557
558~’    Filenames containing trailing tildes are used for editor  backup
559              files,  which  are ignored.  Tildes are allowed anywhere else in
560              the name.
561
562dpkg-old
563dpkg-dist
564dpkg-new
565dpkg-tmp
566              These names may not appear at the end  of  a  name.   These  are
567              saved  copies of conffiles used by the dpkg package manager, and
568              will be ignored.
569

SECURITY

571   Untrusted users
572       Note that giving untrusted users root access to chroots  is  a  serious
573       security  risk!  Although the untrusted user will only have root access
574       to files inside the chroot, in practice there are many obvious ways  of
575       breaking  out of the chroot and of disrupting services on the host sys‐
576       tem.  As always, this boils down to trust.
577
578       Do not give chroot root access to users you would not trust  with  root
579       access to the host system.
580
581   Profiles
582       Depending upon which profile you have configured with the script-config
583       option, different filesystems will be mounted inside  the  chroot,  and
584       different  files  will  be  copied into the chroot from the host.  Some
585       profiles will mount the host's /dev, while others will not.  Some  pro‐
586       files  also bind mount additional parts of the host filesystem in order
587       to allow use of certain features, including user's home directories and
588       specific  parts  of /var.  Check the profile's fstab file to be certain
589       of what will be mounted, and the other profile files to see which files
590       and  system databases will be copied into the chroot.  Choose a differ‐
591       ent profile or edit the files to further restrict what is  made  avail‐
592       able inside the chroot.
593
594       There  is a tradeoff between security (keeping the chroot as minimal as
595       possible) and usability (which sometimes requires access  to  parts  of
596       the host filesystem).  The different profiles make different tradeoffs,
597       and it is important that you assess which meets the  security/usability
598       tradeoff you require.
599

EXAMPLE

601       # Sample configuration
602
603       [sid]
604       type=plain
605       description=Debian unstable
606       description[fr_FR]=Debian instable
607       directory=/srv/chroot/sid
608       priority=3
609       users=jim
610       groups=sbuild
611       root-users=rleigh
612       aliases=unstable,default
613
614       [etch]
615       type=block-device
616       description=Debian testing (32-bit)
617       priority=2
618       groups=users
619       #groups=sbuild-security
620       aliases=testing
621       device=/dev/hda_vg/etch_chroot
622       mount-options=-o atime
623       personality=linux32
624
625       [sid-file]
626       type=file
627       description=Debian sid file-based chroot
628       priority=3
629       groups=sbuild
630       file=/srv/chroots/sid.tar.gz
631
632       [sid-snapshot]
633       type=lvm-snapshot
634       description=Debian unstable LVM snapshot
635       priority=3
636       groups=sbuild
637       users=rleigh
638       source-root-users=rleigh
639       source-root-groups=admin
640       device=/dev/hda_vg/sid_chroot
641       mount-options=-o atime,sync,user_xattr
642       lvm-snapshot-options=--size 2G
643

FILES

645   Chroot definitions
646       /etc/schroot/schroot.conf
647              The system-wide chroot definition file.  This file must be owned
648              by the root user, and not be writable by other.
649
650       /etc/schroot/chroot.d
651              Additional chroot definitions may be placed in files under  this
652              directory.   They  are  treated  in  exactly that same manner as
653              /etc/schroot/schroot.conf.  Each file may contain  one  or  more
654              chroot definitions.
655
656   Setup script configuration
657       The  directory  /etc/schroot/default contains the default settings used
658       by setup scripts.
659
660       config Main configuration file read by setup scripts.   The  format  of
661              this file is described in schroot-script-config(5).  This is the
662              default value for the script-config key.   Note  that  this  was
663              formerly   named  /etc/schroot/script-defaults.   The  following
664              files are referenced by default:
665
666       copyfiles
667              A list of files to copy into the chroot from  the  host  system.
668              Note   that   this   was   formerly   named   /etc/schroot/copy‐
669              files-defaults.
670
671       fstab  A file in  the  format  decribed  in  fstab(5),  used  to  mount
672              filesystems  inside  the chroot.  The mount location is relative
673              to the root of the chroot.  Note that this  was  formerly  named
674              /etc/schroot/mount-defaults.
675
676       nssdatabases
677              System   databases   (as   described  in  /etc/nsswitch.conf  on
678              GNU/Linux systems) to copy into the chroot from the host.   Note
679              that this was formerly named /etc/schroot/nssdatabases-defaults.
680

AUTHORS

682       Roger Leigh.
683
685       Copyright © 2005-2012  Roger Leigh <rleigh@debian.org>
686
687       schroot  is  free  software:  you  can redistribute it and/or modify it
688       under the terms of the GNU General Public License as published  by  the
689       Free  Software Foundation, either version 3 of the License, or (at your
690       option) any later version.
691

SEE ALSO

693       sbuild(1),   schroot(1),   schroot-script-config(5),    schroot-faq(7),
694       mount(8).
695
696
697
698Version 1.6.10                    05 May 2014                  SCHROOT.CONF(5)
Impressum