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 Vampire DC
  45 ----------
  46 Vampire DC gets its name for historic reasons. It's one of the few testenvs
  47 where 2 DCs are joined together, so it's used for a lot of DRS replication
  48 testing. Basically its main job is to 'suck' the database changes out of
  49 another DC (the 'ad_dc_ntfvs' DC).
  50
  51 There's also a 'vampire_2000_dc' that joins the 'fl2000dc' DC, although that's
  52 not used very much.
  53
  54 Backup/restore testenvs
  55 -----------------------
  56 Several testenvs are created to test the domain backup/restore commands. These
  57 testenvs verify that we can backup and restore a domain's database, start
  58 Samba against it, and the restored database is actually functional. There are
  59 several different flavours of backups (to cover different use-cases), so there
  60 are separate testenvs for each one.
  61
  62 - backupfromdc: A fairly plain AD DC used as the base to generate the
  63     backup-files. These backup-files will then seed the domain database
  64     for the separate testenvs below.
  65     Backupfromdc's other unique feature is that it's the only testenv that gets
  66     provisioned with a non-default site, i.e. Default-First-Site-Name doesn't
  67     exist.
  68 - restoredc: tests the 'backup online' option. Online backups are similar to
  69     doing a DC join.
  70     Restoredc's other unique feature is that is has SMBv1 disabled.
  71 - offlinebackupdc: tests the 'backup offline' option. Offline backups capture
  72     the raw DB files on disk (safely).
  73 - renamedc: tests the 'backup rename' option, where the domain and realm are
  74     renamed.
  75 - labdc: one of the use-cases for the backup tool is to create a realistic
  76     pre-production testbed, based off a production DC. This testenv simulates
  77     that process. It uses the 'backup rename --no-secrets' option.
  78
  79 customdc testenv
  80 ----------------
  81 The customdc is a special testenv that's only used for manual testing, rather
  82 than the automated tests most testenvs are primarily used for.
  83
  84 The customdc testenv also uses the backup/restore tool, however, it is quite
  85 special. Instead of the backup-file being automatically generated from a
  86 vanilla AD DC (i.e. backupfromdc), you can specify any backup-file you like.
  87
  88 To run the testenv, you need to specify a 'BACKUP_FILE' shell variable, e.g.
  89
  90 BACKUP_FILE=/tmp/samba-backup-50k-dc-0-mdb-50k-offline.tar.bz2 \
  91     SELFTEST_TESTENV=customdc make testenv
  92
  93 The main use-case for the customdc is testing changes against a large
  94 database. Adding users is very time-consuming, so it's much quicker to populate
  95 a domain with users once, take a backup, and then you can spin up a testenv
  96 based on the backup multiple times.
  97
  98 Another use-case is that if you get a database that's corrupted or in a bad
  99 state, then you could save a backup and be able to easily get the database back
 100 into the bad state. This allows you to try different commands to diagnose/fix
 101 the issue, without fear of never seeing the problem again.
 102
 103 You could even spin up a 'lab DC' inside a testenv, by taking a backup of a
 104 real network DC.
 105
 106 preforkrestartdc testenv
 107 ------------------------
 108 Used to test killing and restarting processes under the pre-fork model. Due to
 109 the destructive nature of the tests, it's not recommended to use this testenv
 110 for anything else.
 111
 112 proclimitdc testenv
 113 -------------------
 114 Used to test process limits on the standard model. It sets the number of
 115 allowed processes artificially low, to test that new connections are refused
 116 correctly.  Due to the limited number of connections accepted, it's not
 117 recommended to use this testenv for anything else.