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  be‐
13       ginning  of a line, or following any other text.  All text right of the
14       ‘#’ 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  de‐
30       tails, 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’, ‘zfs-snap‐
37              shot’ and ‘lvm-snapshot’.  If empty or omitted, the default type
38              is ‘plain’.  Note that ‘plain’ chroots do not run setup  scripts
39              and 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 in‐
48              dicating whether a distribution is older than another.  For  ex‐
49              ample,  “oldstable” and “oldstable-security” might be ‘0’, while
50              “stable” and “stable-security” are ‘1’,  “testing”  is  ‘2’  and
51              “unstable”  is  ‘3’.  The values are not important, but the dif‐
52              ference 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 ch‐
91              root.   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 ‘de‐
101              fault’.  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,
109              setup.copyfiles,  setup.fstab  and  setup.nssdatabases  are  set
110              based 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  re‐
118              lease.   Note that profile is equivalent to script-config if the
119              file sourced by script-config only contains the  standard  vari‐
120              ables  provided by schroot; if any additional variables or shell
121              script fragments have been added, please also set  setup.config,
122              which  will  continue  to  allow this file to be sourced.  It is
123              recommended to replace the use of the sourced  file  with  addi‐
124              tional keys in schroot.conf where possible, but it will continue
125              to be possible to source an additional configuration file  using
126              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              configurations  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 in‐
179              clude ‘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 op‐
200              tion is useful when using a 32-bit chroot on 64-bit system,  for
201              example.   Valid  options  on Linux are ‘bsd’, ‘hpux’, ‘irix32’,
202              ‘irix64’, ‘irixn32’, ‘iscr4’, ‘linux’, ‘linux32’, ‘linux_32bit’,
203              ‘osf4’, ‘osr5’, ‘riscos’, ‘scorvr3’, ‘solaris’, ‘sunos’, ‘svr4’,
204              ‘uw7’, ‘wysev386’, and ‘xenix’.  The default value  is  ‘linux’.
205              There  is  also  the special option ‘undefined’ (personality not
206              set).  For a 32-bit chroot on a 64-bit system, ‘linux32’ is  the
207              option required.  The only valid option for non-Linux systems is
208              ‘undefined’.  The default value for non-Linux systems is  ‘unde‐
209              fined’.
210
211       preserve-environment=true|false
212              By default, the environment will not be preserved inside the ch‐
213              root, 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  or‐
230              der  to  remove  environment variables which may pose a security
231              risk.  Any environment variable matching the specified POSIX ex‐
232              tended regular expression will be removed prior to executing any
233              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 ch‐
246       roots; it is the responsibility of the system administrator to  config‐
247       ure  such  chroots by hand, whereas directory chroots are automatically
248       configured.  Additionally, directory chroots implement  the  filesystem
249       union chroot options (see “Filesystem Union chroot options”, below).
250
251       These chroot types have an additional (mandatory) configuration option:
252
253       directory=directory
254              The  directory containing the chroot environment.  This is where
255              the root will be changed to when executing a login  shell  or  a
256              command.   The  directory  must  exist and have read and execute
257              permissions to allow users access to it.   Note  that  on  Linux
258              systems  it  will be bind-mounted elsewhere for use as a chroot;
259              the directory for ‘plain’ chroots is mounted  with  the  --rbind
260              option to mount(8), while for ‘directory’ chroots --bind is used
261              instead so that sub-mounts are not preserved (they should be set
262              in the fstab file just like in /etc/fstab on the host).
263
264   File chroots
265       Chroots  of  type ‘file’ are files on the current filesystem containing
266       an archive of the chroot files.  They implement the source  chroot  op‐
267       tions  (see “Source chroot options”, below).  Note that a corresponding
268       source chroot (of type ‘file’) will be created for each chroot of  this
269       type; this is for convenient access to the source archive, e.g. for the
270       purpose of updating. These additional options are also implemented:
271
272       file=filename
273              The file containing the archived chroot environment (mandatory).
274              This  must  be  a tar (tape archive), optionally compressed with
275              gzip, bzip2, xz, lzop or lz4.  The file extensions used  to  de‐
276              termine   the   type   are  .tar,  .tar.gz,  .tar.bz2,  .tar.xz,
277              .tar.lzop, .tar.lz4, .tgz, .tbz, .txz,  .tzo  and  .tlz4.   This
278              file  must  be  owned  by  the root user, and not be writable by
279              other.  Note that zip archives are no longer supported; zip  was
280              not  able  to  archive  named pipes and device nodes, so was not
281              suitable for archiving chroots.
282
283       location=path
284              This is the path to the chroot inside the archive.  For example,
285              if  the archive contains a chroot in /squeeze, you would specify
286              “/squeeze” here.  If the chroot is the only  thing  in  the  ar‐
287              chive, i.e. / is the root filesystem for the chroot, this option
288              should be left blank, or omitted entirely.
289
290   Loopback chroots
291       Chroots of type ‘loopback’ are a filesystem  available  as  a  file  on
292       disk, accessed via a loopback mount.  The file will be loopback mounted
293       and unmounted on demand.  Loopback chroots implement the mountable  ch‐
294       root  and  filesystem  union  chroot options (see “Mountable chroot op‐
295       tions” and “Filesystem Union chroot options”,  below),  plus  an  addi‐
296       tional option:
297
298       file=filename
299              This  is the filename of the file containing the filesystem, in‐
300              cluding the absolute path.  For example “/srv/chroot/sid”.
301
302   Block device chroots
303       Chroots of type ‘block-device’ are a filesystem  available  on  an  un‐
304       mounted  block device.  The device will be mounted and unmounted on de‐
305       mand.  Block device chroots implement the mountable chroot and filesys‐
306       tem  union chroot options (see “Mountable chroot options” and “Filesys‐
307       tem Union chroot options”, below), plus an additional option:
308
309       device=device
310              This is the device name of the block device, including the abso‐
311              lute path.  For example, “/dev/sda5”.
312
313   Btrfs snapshot chroots
314       Chroots  of  type ‘btrfs-snapshot’ are a Btrfs snapshot created from an
315       existing Btrfs subvolume on a mounted  Btrfs  filesystem.   A  snapshot
316       will  be created from this source subvolume on demand at the start of a
317       session, and then the snapshot will be mounted.  At the end of the ses‐
318       sion, the snapshot will be unmounted and deleted.  This chroot type im‐
319       plements the source chroot options (see “Source  chroot  options”,  be‐
320       low).   Note  that  a corresponding source chroot (of type ‘directory’)
321       will be created for each chroot of this type; this  is  for  convenient
322       access  to  the source volume. These additional options are also imple‐
323       mented:
324
325       btrfs-source-subvolume=directory
326              The directory containing the source subvolume.
327
328       btrfs-snapshot-directory=directory
329              The directory in which to  store  the  snapshots  of  the  above
330              source subvolume.
331
332   ZFS snapshot chroots
333       Chroots of type ‘zfs-snapshot’ are a ZFS clone created from an existing
334       ZFS dataset.  A snapshot and clone will be  created  from  this  source
335       subvolume  on demand at the start of a session, and then the clone will
336       be mounted.  At the end of the session, the clone will be unmounted and
337       the  clone  and  snapshot will be deleted.  This chroot type implements
338       the source chroot options (see “Source chroot options”,  below).   Note
339       that  a  corresponding source chroot (of type ‘directory’) will be cre‐
340       ated for each chroot of this type; this is for convenient access to the
341       source volume. These additional options are also implemented:
342
343       zfs-dataset=dataset_name
344              Name of the ZFS source dataset to use.
345
346       zfs-snapshot-options=snapshot_options
347              Snapshot  options.   These are additional options to pass to zfs
348              snapshot.
349
350   LVM snapshot chroots
351       Chroots of type ‘lvm-snapshot’ are a filesystem  available  on  an  LVM
352       logical volume (LV).  A snapshot LV will be created from this LV on de‐
353       mand, and then the snapshot will be mounted.  At the end  of  the  ses‐
354       sion, the snapshot LV will be unmounted and removed.
355
356       LVM  snapshot  chroots implement the source chroot options (see “Source
357       chroot options”, below), and all the options for ‘block-device’.   Note
358       that  a  corresponding  source  chroot (of type ‘block-device’) will be
359       created for each chroot of this type; this is for convenient access  to
360       the source device. This additional option is also implemented:
361
362       lvm-snapshot-options=snapshot_options
363              Snapshot  options.   These  are  additional  options  to pass to
364              lvcreate(8).  For example, “-L 2g” to create a snapshot 2 GiB in
365              size.   Note: the LV name (-n), the snapshot option (-s) and the
366              original LV path may not be specfied here; they are set automat‐
367              ically by schroot.
368
369   Custom chroots
370       Chroots  of type ‘custom’ are a special type of chroot, used for imple‐
371       menting new types of chroot not supported by any of  the  above  chroot
372       types.   This  may  be useful for implementing and testing a new chroot
373       type without needing to write any C++ code.  However, you will need  to
374       write  your own setup script to do the setup work, since by itself this
375       chroot type does very little.  You will also need to add custom keys to
376       your chroot definition for use in the setup script; unlike the configu‐
377       ration for the above chroot types, no validation of  the  options  will
378       take  place  unless  you  do  it  yourself in your custom setup script.
379       These additional options are also implemented:
380
381       custom-session-cloneable=true|false
382              Set whether or not sessions may be cloned using this chroot (en‐
383              abled by default).
384
385       custom-session-purgeable=true|false
386              Set  whether  or  not  sessions  may be cloned using this chroot
387              (disabled by default).
388
389       custom-source-cloneable=true|false
390              Set whether or not source chroots may be cloned using  this  ch‐
391              root (disabled by default).
392
393   Source chroot options
394       The  ‘btrfs-snapshot’, ‘file’ and ‘lvm-snapshot’ chroot types implement
395       source chroots.  Additionally, chroot types with union support  enabled
396       implement  source  chroots  (see “Filesystem Union chroot options”, be‐
397       low).  These are chroots which automatically create  a  copy  of  them‐
398       selves  before use, and are usually session managed.  These chroots ad‐
399       ditionally provide an extra chroot in the source: namespace,  to  allow
400       convenient access to the original (non-snapshotted) data, and to aid in
401       chroot maintenance.  I.e. for a chroot named wheezy (chroot:wheezy),  a
402       corresponding  source:wheezy chroot will be created.  For compatibility
403       with older versions of schroot which did not support namespaces, a  ch‐
404       root  with a -source suffix appended to the chroot name will be created
405       in addition (i.e. wheezy-source using the above  example).   Note  that
406       these  compatibility names will be removed in schroot 1.5.0, so the use
407       of the source: namespace is preferred over the use of the -source  suf‐
408       fix form.  See schroot(1) for further details.
409
410       These chroots provide the following additional options:
411
412       source-clone=true|false
413              Set  whether  the  source  chroot should be automatically cloned
414              (created) for this chroot.  The default is true to automatically
415              clone,  but  if desired may be disabled by setting to false.  If
416              disabled, the source chroot will be inaccessible.
417
418       source-users=user1,user2,...
419              A comma-separated list of users which are allowed access to  the
420              source  chroot.   If  empty or omitted, no users will be allowed
421              access.  This will become the users option in the source chroot.
422
423       source-groups=group1,group2,...
424              A comma-separated list of groups which are allowed access to the
425              source  chroot.   If  empty or omitted, no users will be allowed
426              access.  This will become the groups option in  the  source  ch‐
427              root.
428
429       source-root-users=user1,user2,...
430              A  comma-separated list of users which are allowed password-less
431              root access to the source chroot.  If empty or omitted, no users
432              will be allowed root access without a password (but if a user is
433              in users, they may gain access with a password).  This will  be‐
434              come  the  root-users option in the source chroot.  See the sec‐
435              tion “Security” below.
436
437       source-root-groups=group1,group2,...
438              A comma-separated list of groups which are allowed password-less
439              root access to the source chroot.  If empty or omitted, no users
440              will be allowed root access without a password (but if a  user's
441              group is in groups, they may gain access with a password).  This
442              will become the root-groups option in the  source  chroot.   See
443              the section “Security” below.
444
445   Mountable chroot options
446       The  ‘block-device’,  ‘loopback’ and ‘lvm-snapshot’ chroot types imple‐
447       ment device mounting.  These are chroots which require the mounting  of
448       a device in order to access the chroot.  These chroots provide the fol‐
449       lowing additional options:
450
451       mount-options=options
452              Mount options for the block device.  These  are  additional  op‐
453              tions    to    pass    to    mount(8).     For    example,   “-o
454              atime,sync,user_xattr”.
455
456       location=path
457              This is the path to the chroot inside the filesystem on the  de‐
458              vice.   For example, if the filesystem contains a chroot in /ch‐
459              root/sid, you would specify “/chroot/sid” here.  If  the  chroot
460              is the only thing on the filesystem, i.e. / is the root filesys‐
461              tem for the chroot, this option should be left blank, or omitted
462              entirely.
463
464   Filesystem Union chroot options
465       The  ‘block-device’,  ‘directory’ and ‘loopback’ chroot types allow for
466       the creation of a session using filesystem unions to overlay the origi‐
467       nal  filesystem  with  a  separate  writable  directory.   The original
468       filesystem is read-only, with any modifications made to the  filesystem
469       made in the overlying writable directory, leaving the original filesys‐
470       tem unchanged.  A union permits multiple sessions to  access  and  make
471       changes  to  a  single chroot simultaneously, while keeping the changes
472       private to each session.  To enable this feature, set union-type to any
473       supported  value.  If enabled, the chroot will also be a source chroot,
474       which will provide additional options  (see  “Source  chroot  options”,
475       above).  All entries are optional.
476
477       union-type=type
478              Set  the union filesystem type.  Currently supported filesystems
479              are ‘aufs’,  ‘overlayfs’,  ‘overlay’  (as  of  Linux  4.0+)  and
480              ‘unionfs’.  The default is ‘none’, which disables this feature.
481
482       union-mount-options=options
483              Union  filesystem mount options (branch configuration), used for
484              mounting the union filesystem specified with  union-type.   This
485              replaces  the  complete “-o” string for mount and allows for the
486              creation of complex filesystem unions.  Note that ‘aufs’, ‘over‐
487              layfs’  and  ‘unionfs’  each  have different supported mount op‐
488              tions.  Note: One can use  the  variables  “${CHROOT_UNION_OVER‐
489              LAY_DIRECTORY}”  and “${CHROOT_UNION_UNDERLAY_DIRECTORY}” to re‐
490              fer to the writable overlay session directory and read-only  un‐
491              derlying  directory  which  are  to  form  the  union.  See sch‐
492              root-setup(5) for a complete variable list.
493
494       union-overlay-directory=directory
495              Specify the directory where the writeable overlay session direc‐
496              tories   will   be   created.   The  default  is  ‘/var/lib/sch‐
497              root/union/overlay’.
498
499       union-underlay-directory=directory
500              Specify the directory where the read-only underlying directories
501              will  be created.  The default is ‘/var/lib/schroot/union/under‐
502              lay’.
503
504   Customisation
505       In addition to the configuration keys listed above, it is  possible  to
506       add custom keys.  These keys will be used to add additional environment
507       variables to the setup script environment when setup scripts  are  run.
508       The only restriction is that the key name consists only of alphanumeric
509       characters and hyphens, begins with an alphabet character and  contains
510       at least one period.  That is to say, that it matches the extended reg‐
511       ular expression “^([a-z][a-z0-9]*\.)+[a-z][a-z0-9-]*$”.
512
513       For example:
514              debian.apt-update=true
515              debian.distribution=unstable
516
517       would set the following environment:
518              DEBIAN_APT_UPDATE=true
519              DEBIAN_DISTRIBUTION=unstable
520
521       Note that it is an error to use different key names which would set the
522       same environment variable by mixing periods and hyphens.
523
524       Custom  configuration  keys  may  also be modified at runtime using the
525       --option option.  However, for security, only selected keys may be mod‐
526       ified.  These keys are specified using the following options:
527
528       user-modifiable-keys=key1,key2,..
529              Set the keys which users may modify using --option.
530
531       root-modifiable-keys=key1,key2,.. Set the keys which the
532              root  user  may  modify using --option.  Note that the root user
533              may use the keys specified in user-modifiable-keys  in  addition
534              to those specified here.
535
536   Localisation
537       Some  keys may be localised in multiple languages.  This is achieved by
538       adding the locale name in square brackets after the key name.  For  ex‐
539       ample:
540              description[en_GB]=British English translation
541
542       This will localise the description key for the en_GB locale.
543              description[fr]=French translation
544
545       This will localise the description key for all French locales.
546

CHROOT NAMES

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

SECURITY

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

EXAMPLE

617       # Sample configuration
618
619       [sid]
620       type=plain
621       description=Debian unstable
622       description[fr_FR]=Debian instable
623       directory=/srv/chroot/sid
624       priority=3
625       users=jim
626       groups=sbuild
627       root-users=rleigh
628       aliases=unstable,default
629
630       [etch]
631       type=block-device
632       description=Debian testing (32-bit)
633       priority=2
634       groups=users
635       #groups=sbuild-security
636       aliases=testing
637       device=/dev/hda_vg/etch_chroot
638       mount-options=-o atime
639       personality=linux32
640
641       [sid-file]
642       type=file
643       description=Debian sid file-based chroot
644       priority=3
645       groups=sbuild
646       file=/srv/chroots/sid.tar.gz
647
648       [sid-snapshot]
649       type=lvm-snapshot
650       description=Debian unstable LVM snapshot
651       priority=3
652       groups=sbuild
653       users=rleigh
654       source-root-users=rleigh
655       source-root-groups=admin
656       device=/dev/hda_vg/sid_chroot
657       mount-options=-o atime,sync,user_xattr
658       lvm-snapshot-options=--size 2G
659

FILES

661   Chroot definitions
662       /etc/schroot/schroot.conf
663              The system-wide chroot definition file.  This file must be owned
664              by the root user, and not be writable by other.
665
666       /etc/schroot/chroot.d
667              Additional  chroot definitions may be placed in files under this
668              directory.  They are treated in  exactly  that  same  manner  as
669              /etc/schroot/schroot.conf.   Each  file  may contain one or more
670              chroot definitions.
671
672   Setup script configuration
673       The directory /etc/schroot/default contains the default  settings  used
674       by setup scripts.
675
676       config Main  configuration  file  read by setup scripts.  The format of
677              this file is described in schroot-script-config(5).  This is the
678              default  value  for  the  script-config key.  Note that this was
679              formerly  named  /etc/schroot/script-defaults.   The   following
680              files are referenced by default:
681
682       copyfiles
683              A  list  of  files to copy into the chroot from the host system.
684              Note that this  was  formerly  named  /etc/schroot/copyfiles-de‐
685              faults.
686
687       fstab  A  file  in  the  format  decribed  in  fstab(5),  used to mount
688              filesystems inside the chroot.  The mount location  is  relative
689              to  the  root  of the chroot.  Note that this was formerly named
690              /etc/schroot/mount-defaults.
691
692       nssdatabases
693              System  databases  (as  described   in   /etc/nsswitch.conf   on
694              GNU/Linux  systems) to copy into the chroot from the host.  Note
695              that this was formerly named /etc/schroot/nssdatabases-defaults.
696

AUTHORS

698       Roger Leigh.
699
701       Copyright © 2005-2012  Roger Leigh <rleigh@debian.org>
702
703       schroot is free software: you can redistribute it and/or modify it  un‐
704       der  the  terms  of  the GNU General Public License as published by the
705       Free Software Foundation, either version 3 of the License, or (at  your
706       option) any later version.
707

SEE ALSO

709       sbuild(1),    schroot(1),   schroot-script-config(5),   schroot-faq(7),
710       mount(8).
711
712
713
714Version 1.6.10                    05 May 2014                  SCHROOT.CONF(5)
Impressum