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 Important notes if adding a new testenv
  20 ---------------------------------------
  21 - When adding a new testenv, in the Perl code it is recommended to always
  22 explicitly specify the --configfile option in the samba-tool command, i.e. add
  23 "env->{CONFIGURATION}" to the samba-tool command. Otherwise, the samba-tool
  24 can try to load smb.conf from the default install location (i.e.
  25 /usr/local/samba/etc/smb.conf). Loading a host-specific smb.conf that's outside
  26 of the testenv is obviously not ideal and something we want to avoid in a
  27 reliable test framework.
  28
  29 'local' disambiguation
  30 ----------------------
  31 You may notice some variation in the target testenv that test suites are run
  32 against, for example "ad_dc" and "ad_dc:local". The main difference is the
  33 ":local" changes the smb.conf that the testenv uses. By default, the testenvs
  34 use the st/client/client.conf config-file, so that they simulate a client
  35 talking to the Samba server. However, some tests may want to simulate running
  36 a command on the Samba server itself. In these cases, the ":local" is used,
  37 which means the testenv uses the Samba server's smb.conf instead (i.e.
  38 st/ad_dc/etc/smb.conf).
  39
  40 Note that several of the testenvs also use local in their name, e.g.
  41 'localvampiredc'. In particular, there's the 'localdc', which is the NetBIOS
  42 name of the DC in the 'ad_dc_ntvfs' testenv.
  43
  44 dns_hub
  45 -------
  46 dns_hub doesn't run a Samba/smbd server like the other testenvs do. It's there
  47 to solve the problem of how to do DNS more nicely in selftest. Running
  48 autobuild can start up a lot of different testenvs, and so we end up with
  49 different DCs running in different domains. Each test suite only wants to talk
  50 to a specific domain at a time. However, by default the tests all use a common
  51 client.conf - essentially the tests are simulating a single client that's
  52 pretending to be in several different domains. The problem is when the test
  53 wants to resolve a DNS host, which DC should it ask? Each DC only knows about its
  54 own realm. dns_hub.py acts as a proxy, so it works out the correct DC to forward
  55 the query to, based on the queried host's realm.
  56
  57 Vampire DC
  58 ----------
  59 Vampire DC gets its name for historic reasons. It's one of the few testenvs
  60 where 2 DCs are joined together, so it's used for a lot of DRS replication
  61 testing. Basically its main job is to 'suck' the database changes out of
  62 another DC (the 'ad_dc_ntfvs' DC).
  63
  64 There's also a 'vampire_2000_dc' that joins the 'fl2000dc' DC, although that's
  65 not used very much.
  66
  67 Backup/restore testenvs
  68 -----------------------
  69 Several testenvs are created to test the domain backup/restore commands. These
  70 testenvs verify that we can backup and restore a domain's database, start
  71 Samba against it, and the restored database is actually functional. There are
  72 several different flavours of backups (to cover different use-cases), so there
  73 are separate testenvs for each one.
  74
  75 - backupfromdc: A fairly plain AD DC used as the base to generate the
  76     backup-files. These backup-files will then seed the domain database
  77     for the separate testenvs below.
  78     Backupfromdc's other unique feature is that it's the only testenv that gets
  79     provisioned with a non-default site, i.e. Default-First-Site-Name doesn't
  80     exist.
  81 - restoredc: tests the 'backup online' option. Online backups are similar to
  82     doing a DC join.
  83     Restoredc's other unique feature is that is has SMBv1 disabled.
  84 - offlinebackupdc: tests the 'backup offline' option. Offline backups capture
  85     the raw DB files on disk (safely).
  86 - renamedc: tests the 'backup rename' option, where the domain and realm are
  87     renamed.
  88 - labdc: one of the use-cases for the backup tool is to create a realistic
  89     pre-production testbed, based off a production DC. This testenv simulates
  90     that process. It uses the 'backup rename --no-secrets' option.
  91
  92 customdc testenv
  93 ----------------
  94 The customdc is a special testenv that's only used for manual testing, rather
  95 than the automated tests most testenvs are primarily used for.
  96
  97 The customdc testenv also uses the backup/restore tool, however, it is quite
  98 special. Instead of the backup-file being automatically generated from a
  99 vanilla AD DC (i.e. backupfromdc), you can specify any backup-file you like.
 100
 101 To run the testenv, you need to specify a 'BACKUP_FILE' shell variable, e.g.
 102
 103 BACKUP_FILE=/tmp/samba-backup-50k-dc-0-mdb-50k-offline.tar.bz2 \
 104     SELFTEST_TESTENV=customdc make testenv
 105
 106 The main use-case for the customdc is testing changes against a large
 107 database. Adding users is very time-consuming, so it's much quicker to populate
 108 a domain with users once, take a backup, and then you can spin up a testenv
 109 based on the backup multiple times.
 110
 111 Another use-case is that if you get a database that's corrupted or in a bad
 112 state, then you could save a backup and be able to easily get the database back
 113 into the bad state. This allows you to try different commands to diagnose/fix
 114 the issue, without fear of never seeing the problem again.
 115
 116 You could even spin up a 'lab DC' inside a testenv, by taking a backup of a
 117 real network DC.
 118
 119 preforkrestartdc testenv
 120 ------------------------
 121 Used to test killing and restarting processes under the pre-fork model. Due to
 122 the destructive nature of the tests, it's not recommended to use this testenv
 123 for anything else.
 124
 125 proclimitdc testenv
 126 -------------------
 127 Used to test process limits on the standard model. It sets the number of
 128 allowed processes artificially low, to test that new connections are refused
 129 correctly.  Due to the limited number of connections accepted, it's not
 130 recommended to use this testenv for anything else.
 131
 132 schema_dc
 133 ----------------
 134 This is a 2-DC testenv setup (schema_dc and schema_pair_dc).
 135 We provision the first DC, and join the second, using an older version of the
 136 schema (2008R2), then start-up Samba. Then, we run a schema upgrade (i.e.
 137 'samba-tool domain schemaupgrade') on the PDC.