| 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. |