selftest/target/README

   1 Selftest target environments (testenvs)
   2 =======================================
   3 Samba's integration testing heavily relies on the automatic creation of a Samba
   4 network. This specialized test environment is generally referred to as a Samba
   5 'testenv'.
   6
   7 A testenv involves starting the Samba server listening on a fake network, which
   8 is established using the socket_wrapper library from cwrap (https://cwrap.org).
   9 All testing is also done as a non-root user using the uid_wrapper library, also
  10 from cwrap.
  11
  12 Samba's test framework uses many different types of testenv. Each testenv is
  13 customized to test a particular Samba feature or configuration. Using cwrap
  14 allows multiple different Samba servers to run at the same time, without
  15 interference.
  16
  17 Some of the different testenvs are described in more detail below.
  18
  19 Backup/restore testenvs
  20 -----------------------
  21 Several testenvs are created to test the domain backup/restore commands. These
  22 testenvs verify that we can backup and restore a domain's database, start
  23 Samba against it, and the restored database is actually functional. There are
  24 several different flavours of backups (to cover different use-cases), so there
  25 are separate testenvs for each one.
  26
  27 - backupfromdc: A fairly plain AD DC used as the base to generate the
  28     backup-files. These backup-files will then seed the domain database
  29     for the separate testenvs below.
  30     Backupfromdc's other unique feature is that it's the only testenv that gets
  31     provisioned with a non-default site, i.e. Default-First-Site-Name doesn't
  32     exist.
  33 - restoredc: tests the 'backup online' option. Online backups are similar to
  34     doing a DC join.
  35 - offlinebackupdc: tests the 'backup offline' option. Offline backups capture
  36     the raw DB files on disk (safely).
  37 - renamedc: tests the 'backup rename' option, where the domain and realm are
  38     renamed.
  39 - labdc: one of the use-cases for the backup tool is to create a realistic
  40     pre-production testbed, based off a production DC. This testenv simulates
  41     that process. It uses the 'backup rename --no-secrets' option.
  42
  43 customdc testenv
  44 ----------------
  45 The customdc is a special testenv that's only used for manual testing, rather
  46 than the automated tests most testenvs are primarily used for.
  47
  48 The customdc testenv also uses the backup/restore tool, however, it is quite
  49 special. Instead of the backup-file being automatically generated from a
  50 vanilla AD DC (i.e. backupfromdc), you can specify any backup-file you like.
  51
  52 To run the testenv, you need to specify a 'BACKUP_FILE' shell variable, e.g.
  53
  54 BACKUP_FILE=/tmp/samba-backup-50k-dc-0-mdb-50k-offline.tar.bz2 \
  55     SELFTEST_TESTENV=customdc make testenv
  56
  57 The main use-case for the customdc is testing changes against a large
  58 database. Adding users is very time-consuming, so it's much quicker to populate
  59 a domain with users once, take a backup, and then you can spin up a testenv
  60 based on the backup multiple times.
  61
  62 Another use-case is that if you get a database that's corrupted or in a bad
  63 state, then you could save a backup and be able to easily get the database back
  64 into the bad state. This allows you to try different commands to diagnose/fix
  65 the issue, without fear of never seeing the problem again.
  66
  67 You could even spin up a 'lab DC' inside a testenv, by taking a backup of a
  68 real network DC.