[PATCH] Create a custom testenv from backup-file for manual testing

[Tim Beale]

Hi Andreas,

Good idea.

For now, I've written up instructions here:
https://wiki.samba.org/index.php/Customdc_testenv

and just linked to it from here:
https://wiki.samba.org/index.php/Writing_Torture_Tests#Test_Environment

One thing I've struggled with in the past is working out how the various
testenvs relate to each other and what exactly it is that they do. I
thought it might be helpful to have some documentation in the code that
explains this. That way, we can keep it up to date each time we add a
new testenv. The attached patch adds a selftest/target/README file as a
potential starting point.

Thanks,
Tim

On 2/11/18 8:09 PM, Andreas Schneider wrote:
> On Tuesday, 30 October 2018 21:52:19 CET Tim Beale via samba-technical wrote:
>> The attached patch allows you to easily spin up any custom testenv that
>> you want, for manual testing. All you need is a backup-file that the
>> testenv DC will be based off.
>>
>> The main use-case is any testing that involves a large database.
>> Creating user accounts is slow. Even with the improvements to the
>> traffic_replay user generation, creating 5,000 users still takes close
>> to 10 minutes. Instead of creating a blank testenv and slowly populating
>> it with users, you can do this step once, take a backup, and then spin
>> up the backup database multiple times as a new testenv.
>>
>> This testenv might be useful in other situations too. E.g. testing
>> migrating databases across samba versions, you spot a DB corruption and
>> want to try diagnosing/fixing it without completely losing the original
>> problem state, you want to create a labdc-replica testenv of a real
>> network, etc.
>>
>> Also fixed a couple of minor dnsupdate problems that were making
>> debugging testenv bootstrapping issues difficult.
> Tim,
>
> could you please document how to use this stuff on
>
> https://wiki.samba.org/index.php/Writing_Torture_Tests
>
>
> Thanks,
>
>
> 	Andreas
>
-------------- next part --------------
From 274a202090e4a8bf1df7df28cd109474c3cf9e2b Mon Sep 17 00:00:00 2001
From: Tim Beale <timbeale at catalyst.net.nz>
Date: Mon, 5 Nov 2018 13:41:08 +1300
Subject: [PATCH 1/2] selftest: Add README documenting the customdc testenv

Also documented the other backup/restore testenvs as well.

Signed-off-by: Tim Beale <timbeale at catalyst.net.nz>
---
 selftest/target/README | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 selftest/target/README

diff --git a/selftest/target/README b/selftest/target/README
new file mode 100644
index 0000000..41e4b77
--- /dev/null
+++ b/selftest/target/README
@@ -0,0 +1,71 @@
+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.
+
+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.
+- 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.
+
+
+
-- 
2.7.4


From e434b88d3821fb41bb13e83f526d5c870226883e Mon Sep 17 00:00:00 2001
From: Tim Beale <timbeale at catalyst.net.nz>
Date: Mon, 5 Nov 2018 14:45:34 +1300
Subject: [PATCH 2/2] selftest: Add some more testenv descriptions

This still doesn't cover all the testenvs comprehensively, but it
pretty much exhausts my knowledge of what the various testenvs do.

Signed-off-by: Tim Beale <timbeale at catalyst.net.nz>
---
 selftest/target/README | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/selftest/target/README b/selftest/target/README
index 41e4b77..85c246c 100644
--- a/selftest/target/README
+++ b/selftest/target/README
@@ -16,6 +16,31 @@ interference.
 
 Some of the different testenvs are described in more detail below.
 
+'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.
+
+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
-- 
2.7.4