diff options
Diffstat (limited to '')
| -rw-r--r-- | selftest/target/README | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/selftest/target/README b/selftest/target/README new file mode 100644 index 0000000..81d7447 --- /dev/null +++ b/selftest/target/README @@ -0,0 +1,137 @@ +Selftest target environments (testenvs) +======================================= +Samba's integration testing heavily relies on the automatic creation of a Samba +network. This specialized test environment is generally referred to as a Samba +'testenv'. + +A testenv involves starting the Samba server listening on a fake network, which +is established using the socket_wrapper library from cwrap (https://cwrap.org). +All testing is also done as a non-root user using the uid_wrapper library, also +from cwrap. + +Samba's test framework uses many different types of testenv. Each testenv is +customized to test a particular Samba feature or configuration. Using cwrap +allows multiple different Samba servers to run at the same time, without +interference. + +Some of the different testenvs are described in more detail below. + +Important notes if adding a new testenv +--------------------------------------- +- When adding a new testenv, in the Perl code it is recommended to always +explicitly specify the --configfile option in the samba-tool command, i.e. add +"env->{CONFIGURATION}" to the samba-tool command. Otherwise, the samba-tool +can try to load smb.conf from the default install location (i.e. +/usr/local/samba/etc/smb.conf). Loading a host-specific smb.conf that's outside +of the testenv is obviously not ideal and something we want to avoid in a +reliable test framework. + +'local' disambiguation +---------------------- +You may notice some variation in the target testenv that test suites are run +against, for example "ad_dc" and "ad_dc:local". The main difference is the +":local" changes the smb.conf that the testenv uses. By default, the testenvs +use the st/client/client.conf config-file, so that they simulate a client +talking to the Samba server. However, some tests may want to simulate running +a command on the Samba server itself. In these cases, the ":local" is used, +which means the testenv uses the Samba server's smb.conf instead (i.e. +st/ad_dc/etc/smb.conf). + +Note that several of the testenvs also use local in their name, e.g. +'localvampiredc'. In particular, there's the 'localdc', which is the NetBIOS +name of the DC in the 'ad_dc_ntvfs' testenv. + +dns_hub +------- +dns_hub doesn't run a Samba/smbd server like the other testenvs do. It's there +to solve the problem of how to do DNS more nicely in selftest. Running +autobuild can start up a lot of different testenvs, and so we end up with +different DCs running in different domains. Each test suite only wants to talk +to a specific domain at a time. However, by default the tests all use a common +client.conf - essentially the tests are simulating a single client that's +pretending to be in several different domains. The problem is when the test +wants to resolve a DNS host, which DC should it ask? Each DC only knows about its +own realm. dns_hub.py acts as a proxy, so it works out the correct DC to forward +the query to, based on the queried host's realm. + +Vampire DC +---------- +Vampire DC gets its name for historic reasons. It's one of the few testenvs +where 2 DCs are joined together, so it's used for a lot of DRS replication +testing. Basically its main job is to 'suck' the database changes out of +another DC (the 'ad_dc_ntfvs' DC). + +There's also a 'vampire_2000_dc' that joins the 'fl2000dc' DC, although that's +not used very much. + +Backup/restore testenvs +----------------------- +Several testenvs are created to test the domain backup/restore commands. These +testenvs verify that we can backup and restore a domain's database, start +Samba against it, and the restored database is actually functional. There are +several different flavours of backups (to cover different use-cases), so there +are separate testenvs for each one. + +- backupfromdc: A fairly plain AD DC used as the base to generate the + backup-files. These backup-files will then seed the domain database + for the separate testenvs below. + Backupfromdc's other unique feature is that it's the only testenv that gets + provisioned with a non-default site, i.e. Default-First-Site-Name doesn't + exist. +- restoredc: tests the 'backup online' option. Online backups are similar to + doing a DC join. + Restoredc's other unique feature is that is has SMBv1 disabled. +- offlinebackupdc: tests the 'backup offline' option. Offline backups capture + the raw DB files on disk (safely). +- renamedc: tests the 'backup rename' option, where the domain and realm are + renamed. +- labdc: one of the use-cases for the backup tool is to create a realistic + pre-production testbed, based off a production DC. This testenv simulates + that process. It uses the 'backup rename --no-secrets' option. + +customdc testenv +---------------- +The customdc is a special testenv that's only used for manual testing, rather +than the automated tests most testenvs are primarily used for. + +The customdc testenv also uses the backup/restore tool, however, it is quite +special. Instead of the backup-file being automatically generated from a +vanilla AD DC (i.e. backupfromdc), you can specify any backup-file you like. + +To run the testenv, you need to specify a 'BACKUP_FILE' shell variable, e.g. + +BACKUP_FILE=/tmp/samba-backup-50k-dc-0-mdb-50k-offline.tar.bz2 \ + SELFTEST_TESTENV=customdc make testenv + +The main use-case for the customdc is testing changes against a large +database. Adding users is very time-consuming, so it's much quicker to populate +a domain with users once, take a backup, and then you can spin up a testenv +based on the backup multiple times. + +Another use-case is that if you get a database that's corrupted or in a bad +state, then you could save a backup and be able to easily get the database back +into the bad state. This allows you to try different commands to diagnose/fix +the issue, without fear of never seeing the problem again. + +You could even spin up a 'lab DC' inside a testenv, by taking a backup of a +real network DC. + +preforkrestartdc testenv +------------------------ +Used to test killing and restarting processes under the pre-fork model. Due to +the destructive nature of the tests, it's not recommended to use this testenv +for anything else. + +proclimitdc testenv +------------------- +Used to test process limits on the standard model. It sets the number of +allowed processes artificially low, to test that new connections are refused +correctly. Due to the limited number of connections accepted, it's not +recommended to use this testenv for anything else. + +schema_dc +---------------- +This is a 2-DC testenv setup (schema_dc and schema_pair_dc). +We provision the first DC, and join the second, using an older version of the +schema (2008R2), then start-up Samba. Then, we run a schema upgrade (i.e. +'samba-tool domain schemaupgrade') on the PDC. |