1 files changed, 112 insertions, 0 deletions
diff --git a/usr/src/test/Readme.smartos b/usr/src/test/Readme.smartos
new file mode 100644
index 0000000000..85f33e7886
--- /dev/null
+++ b/usr/src/test/Readme.smartos
@@ -0,0 +1,112 @@
+#
+# This file and its contents are supplied under the terms of the
+# Common Development and Distribution License ("CDDL"), version 1.0.
+# You may only use this file in accordance with the terms of version
+# 1.0 of the CDDL.
+#
+# A full copy of the text of the CDDL should have accompanied this
+# source.  A copy of the CDDL is also available via the Internet at
+# http://www.illumos.org/license/CDDL.
+#
+
+#
+# Copyright 2018, Joyent, Inc.
+#
+
+I) Introduction
+
+The procedure to run the illumos tests under SmartOS is unlike that for
+other distributions because of the zone-centric nature of the distribution,
+and because there is no built-in package management for the global zone.
+
+This Readme assumes you will run the tests in the global zone, as root.
+Although it is possible to run some of the tests within a non-global zone, as a
+user configured within that zone, that approach is not described here.
+
+Some test suites, such as the ZFS tests, assume there are available disks to
+use for the test run. For more information on running the ZFS tests, see II.4).
+
+II) Setup to Run the Tests
+
+1) The tests currently require python27 to run, so you need to install this in
+   the global zone. The easiest way to do this is with pkgsrc using the
+   following procedure:
+
+   a) Get a copy of the following bootstrap tarball onto the test machine:
+      https://pkgsrc.joyent.com/packages/SmartOS/bootstrap/bootstrap-2014Q4-multiarch.tar.gz
+
+   b) Install the bootstrap tarball:
+      # gzcat bootstrap-2014Q4-multiarch.tar.gz | (cd /; tar -xpf -)
+
+   c) Install python27:
+      pkgin in python27
+
+2) You need to get the tests from your build machine onto the test machine's
+   global zone. This can be done in whatever way is easiest for you. Here is
+   one simple way:
+
+   a) On your build machine, in your fully built smartos-live proto area,
+      create a tarball of the test directory:
+      % cd proto/opt
+      % tar czf ../opt.tgz *
+
+
+   b) Copy the tarball from the build machine to the test machine running
+      SmartOS (the next step assumes you placed the tarball into the /zones
+      directory).
+
+3) In the global zone on your test machine, install the tests.
+
+   # cd /opt
+   # tar xf /zones/opt.tgz
+
+4) (optional) Running the ZFS tests requires a few additional steps.
+   The ZFS test suite must _not_ be run as the root user. Instead we will create
+   a new user called 'ztest' that we will use to run the tests.
+
+   a) Make sure the system has three unused 10GB disks. These disks must not be
+      associated with an existing zpool.
+
+   b) In preparation for installing 'sudo' and adding a user for the ZFS test
+      suite, edit /etc/passwd and /etc/shadow:
+      # echo "cyrus:x:100:1::/home/cyrus:/bin/sh" >> /etc/passwd
+      # echo "ztest:x:101:1::/home/ztest:/bin/sh" >> /etc/passwd
+      # echo "cyrus:*LK*:::::::" >> /etc/shadow
+      # echo "ztest:*LK*:::::::" >> /etc/shadow
+
+      Note: The /etc/passwd modifications will not persist after reboot.
+
+   c) sudo and truncate must be installed. They will later be linked into the
+      appropriate location by the ZFS test suite.
+      # pkgin in sudo
+      # pkgin in coreutils # provides truncate
+
+   d) The ztest user must be able to use sudo without a password:
+      # echo "ztest ALL=(ALL) NOPASSWD: ALL" >> /opt/local/etc/sudoers
+
+   e) Change to the 'ztest' user and set environment variables. In this example
+      DISKS is the list of three unused disks that will be used to run the
+      tests. KEEP is a list of zpools that the tests should _not_ destroy:
+      # su ztest
+      $ export DISKS='c2t1d0 c2t2d0 c2t3d0'
+      $ export KEEP='zones'
+
+      Beware that data loss will occur for any data residing on DISKS and
+      failure to specify a KEEP pool may also lead to data loss.
+
+III) Run the Tests
+
+Now that setup is complete, you can run the tests using the normal procedure.
+For example:
+
+    # /opt/util-tests/bin/utiltest
+or
+    # /opt/os-tests/bin/ostest
+or (as 'ztest' user after 4.e above)
+    $ /opt/zfs-tests/bin/zfstest
+
+IV) Running New Tests
+
+During development, if you are creating or updating new tests, you can repeat
+steps 2 and 3 as often as necessary to make the new tests available on the test
+machine.