From 5945988d7373d65d5a38b11ade84fabe9ac7bb68 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Aug 29 2013 13:22:22 +0000 Subject: Add man pages for testing tools Add man pages for ipa-run-tests, ipa-test-task, and ipa-test-config. https://fedorahosted.org/freeipa/ticket/3855 (part 5) --- diff --git a/.gitignore b/.gitignore index 738b00b..5252dad 100644 --- a/.gitignore +++ b/.gitignore @@ -81,6 +81,11 @@ ipa-client/py-compile ipa-client/stamp-h1 ipa-client/version.m4 ipatests/test_xmlrpc/service.crt +ipatests/man/aclocal.m4 +ipatests/man/autom4te.cache/ +ipatests/man/config.status +ipatests/man/install-sh +ipatests/man/missing freeipa.spec ipapython/setup.py ipapython/version.py diff --git a/Makefile b/Makefile index 674143b..a21cf7e 100644 --- a/Makefile +++ b/Makefile @@ -71,6 +71,9 @@ client-autogen: version-update cd ipa-client; if [ ! -e Makefile ]; then ../autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=$(LIBDIR); fi cd install; if [ ! -e Makefile ]; then ../autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=$(LIBDIR); fi +tests-man-autogen: version-update + cd ipatests/man; if [ ! -e Makefile ]; then ../../autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=$(LIBDIR); fi + install: all server-install tests-install @for subdir in $(SUBDIRS); do \ (cd $$subdir && $(MAKE) $@) || exit 1; \ @@ -153,8 +156,9 @@ server-install: server $(PYTHON) setup.py install --root $(DESTDIR); \ fi -tests: version-update +tests: version-update tests-man-autogen cd ipatests; $(PYTHON) setup.py build + cd ipatests/man && $(MAKE) all tests-install: tests if [ "$(DESTDIR)" = "" ]; then \ @@ -162,6 +166,7 @@ tests-install: tests else \ cd ipatests; $(PYTHON) setup.py install --root $(DESTDIR); \ fi + cd ipatests/man && $(MAKE) install archive: -mkdir -p dist diff --git a/freeipa.spec.in b/freeipa.spec.in index d02ffe2..9ef34b2 100644 --- a/freeipa.spec.in +++ b/freeipa.spec.in @@ -830,9 +830,15 @@ fi %{_bindir}/ipa-test-config %{_bindir}/ipa-test-task %{python_sitelib}/ipatests-*.egg-info +%{_mandir}/man1/ipa-run-tests.1.gz +%{_mandir}/man1/ipa-test-config.1.gz +%{_mandir}/man1/ipa-test-task.1.gz %endif # ONLY_CLIENT %changelog +* Wed Aug 29 2013 Petr Viktorin - 3.3.0-2 +- Add man pages to the tests subpackage + * Mon Aug 12 2013 Petr Viktorin - 3.3.0-1 - Downgrade required version of python-paramiko for the tests subpackage diff --git a/ipatests/man/Makefile.am b/ipatests/man/Makefile.am new file mode 100644 index 0000000..fcd3d1d --- /dev/null +++ b/ipatests/man/Makefile.am @@ -0,0 +1,18 @@ +# This file will be processed with automake-1.7 to create Makefile.in + +AUTOMAKE_OPTIONS = 1.7 + +NULL= + +man1_MANS = \ + ipa-run-tests.1 \ + ipa-test-config.1 \ + ipa-test-task.1 \ + $(NULL) + +install-data-hook: + @for i in $(man1_MANS) ; do gzip -f $(DESTDIR)$(man1dir)/$$i ; done + +MAINTAINERCLEANFILES = \ + Makefile.in \ + $(NULL) diff --git a/ipatests/man/configure.ac b/ipatests/man/configure.ac new file mode 100644 index 0000000..8ddb93a --- /dev/null +++ b/ipatests/man/configure.ac @@ -0,0 +1,24 @@ +AC_PREREQ(2.59) +m4_include(../../version.m4) +AC_INIT([ipa-tests], + IPA_VERSION, + [https://hosted.fedoraproject.org/projects/freeipa/newticket]) + +AM_INIT_AUTOMAKE([foreign]) + +AM_MAINTAINER_MODE + +AC_SUBST(VERSION) +AC_SUBST([INSTALL_DATA], ['$(INSTALL) -m 644 -p']) + +AC_PROG_MKDIR_P +AC_PROG_AWK +AC_PROG_SED + +# Files + +AC_CONFIG_FILES([ + Makefile +]) + +AC_OUTPUT diff --git a/ipatests/man/ipa-run-tests.1 b/ipatests/man/ipa-run-tests.1 new file mode 100644 index 0000000..66c2a0b --- /dev/null +++ b/ipatests/man/ipa-run-tests.1 @@ -0,0 +1,63 @@ +.\" A man page for ipa-run-tests +.\" Copyright (C) 2013 Red Hat, Inc. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see . +.\" +.\" Author: Petr Viktorin +.\" +.TH "ipa-run-tests" "1" "Aug 29 2013" "FreeIPA" "FreeIPA Manual Pages" +.SH "NAME" +ipa\-run\-tests \- Run the FreeIPA test suite +.SH "SYNOPSIS" +ipa\-run\-tests [options] +.SH "DESCRIPTION" +ipa\-run\-tests is a wrapper around nosetests that run the FreeIPA test suite. +It is intended to be used for developer testing and in continuous +integration systems. + +It loads IPA-internal Nose plugins ordered-tests and beakerlib. +The ordered-tests plugin is enabled automatically. + +The FreeIPA test suite installed system\-wide is selected via Nose's \-\-where +option. +It is possible to select a subset of the entire test suite by specifying +a test file relative to the ipatests package, for example: + + ipa-run-tests test_integration/test_simple_replication.py + +.SH "OPTIONS" +All command-line options are passed to the underlying Nose runner. +See nosetests(1) for a complete list. + +The internal IPA plugins add an extra option: + +.TP +\fB\-\-with-beakerlib\fR +Enable BeakerLib integration. +Test phases, failures and passes, and log messages are reported using +beakerlib(1) commands. +This option requires the beakerlib.sh script to be sourced. + +.SH "EXIT STATUS" +0 if the command was successful + +nonzero if any error or failure occurred + +.SH "CONFIGURATION" +Please see ipa-test-config(1) for a description of configuration environment +variables. + +.SH "REFERENCES" +A full description of the FreeIPA integration testing framework is available at +http://www.freeipa.org/page/V3/Integration_testing diff --git a/ipatests/man/ipa-test-config.1 b/ipatests/man/ipa-test-config.1 new file mode 100644 index 0000000..4b998ad --- /dev/null +++ b/ipatests/man/ipa-test-config.1 @@ -0,0 +1,157 @@ +.\" A man page for ipa-test-config +.\" Copyright (C) 2013 Red Hat, Inc. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see . +.\" +.\" Author: Petr Viktorin +.\" +.TH "ipa-test-config" "1" "Aug 29 2013" "FreeIPA" "FreeIPA Manual Pages" +.SH "NAME" +ipa\-test\-config \- Generate FreeIPA test configuration for use in Bash scripts +.SH "SYNOPSIS" +ipa\-test\-config [options] +.br +ipa\-test\-config [options] --global +.br +ipa\-test\-config [options] hostname +.SH "DESCRIPTION" +The FreeIPA integration test suite is configured by setting environment +variables. +The ipa\-run\-tests command reads these variables and prints detailed +configuration for shell-based scripts to standard output. +The output of ipa\-run\-tests consists of export statements that can be +sourced by Bash. + +If run without arguments, it prints out configuration specific to the local +host. +Another host may be specified as an argument, or via the \-\-master, +\-\-replica, and \-\-client options. +With the --global option, it prints only configuration that is not specific to +any host. + +.SH "OPTIONS" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print out the command's usage and exit +.TP +\fB\-\-global\fR +Output global configuration. +.TP +\fB\-\-domain\fR +Output configuration for the given domain (environment). +May be given as an index or name. +By default, domain 1 is used. +.TP +\fB\-\-master\fR +Output configuration for the master +.TP +\fB\-\-replica\fR +Output configuration for the replica with the given number +.TP +\fB\-\-replica\fR +Output configuration for the client with the given number +.TP +\fB\-\-no\-simple\fR +Do not output Simple Vars. +These are normally included for backwards compatibility. + +.SH "ENVIRONMENT VARIABLES" + +.TP +Host configuration: + +.TP +\fB$MASTER\fR + FQDN of the first IPA server +.TP +\fB$REPLICA\fR + FQDNs of other IPA servers (space-separated) +.TP +\fB$CLIENT\fR + FQDNs of IPA clients (space-separated) +.TP +\fB$MASTER_env2\fR, \fB$REPLICA_env2\fR, \fB$CLIENT_env2\fR, \fB$MASTER_env3\fR, ... + can be used for additional domains when needed +.TP +\fB$BEAKER\fR\fB_IP_env\fR, e.g. \fB$BEAKERREPLICA1_IP_env1\fR + the IP address of the given host + Default: resolved via gethostbyname (or DNS if $IPv6SETUP is set) + +.TP +Basic configuration: + +.TP +\fB$IPATEST_DIR\fR + Directory for test data on the remote hosts + Default: /root/ipatests +.TP +\fB$DNSFORWARD\fR + IP of a DNS forwarder + Default: 8.8.8.8 +.TP +\fB$IPA_ROOT_SSH_PASSWORD\fR + root password for the remote machines + Used if $IPA_ROOT_SSH_KEY is not set. +.TP +\fB$IPA_ROOT_SSH_KEY\fR + name of a file containing the private RSA key for root on the remote machines + Default: ~/.ssh/id_rsa + +.TP +Test customization: + +.TP +\fB$DOMAIN\fR + IPA domain name + Default: taken from $MASTER +.TP +\fB$NISDOMAIN\fR + NIS domain name + Default: ipatest +.TP +\fB$NTPSERVER\fR + NIS domain name + Default: ipatest +.TP +\fB$IPv6SETUP\fR + Set to TRUE for IPv6-only connectivity +.TP +\fB$IPADEBUG\fR + Set to enable test debugging + +.TP +\fB$ADMINID\fR + Admin username + Default: admin +.TP +\fB$ADMINPW\fR + Admin user password + Default: Secret123 +.TP +\fB$ROOTDN\fR + Directory manager DN + Default: cn=Directory Manager +.TP +\fB$ROOTDNPWD\fR + Directory manager password + Default: Secret123 + +.SH "EXIT STATUS" +0 if the command was successful + +1 if an error occurred + +.SH "REFERENCES" +A full description of the FreeIPA integration testing framework is available at +http://www.freeipa.org/page/V3/Integration_testing diff --git a/ipatests/man/ipa-test-task.1 b/ipatests/man/ipa-test-task.1 new file mode 100644 index 0000000..b625b28 --- /dev/null +++ b/ipatests/man/ipa-test-task.1 @@ -0,0 +1,126 @@ +.\" A man page for ipa-test-task +.\" Copyright (C) 2013 Red Hat, Inc. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see . +.\" +.\" Author: Petr Viktorin +.\" +.TH "ipa-test-task" "1" "Aug 29 2013" "FreeIPA" "FreeIPA Manual Pages" +.SH "NAME" +ipa\-test\-task \- Run a task for FreeIPA testing +.SH "SYNOPSIS" +ipa\-test\-task -h +.br +ipa\-test\-task [global-options] TASK [task-options] +.SH "DESCRIPTION" +Run a task using FreeIPA integration testing configuration. +This tool is meant for use in scripts that test FreeIPA functionality. +See ipa-test-config(1) for FreeIPA integration test configuration. + +This tool should never be run in a production environment. +It is not designed with security in mind. + +.SH "GLOBAL OPTIONS" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print out the command's usage and exit. +If given after a subcommand, prints that subcommand's usage message. + +.TP +\fB\-\-with\-beakerlib\fR +Enable BeakerLib integration. +Log messages are reported via beakerlib(1) commands. +This option requires an active BeakerLib phase. + +.SH "SUBCOMMANDS" +.TP +\fBipa\-test\-task install\-master [\-\-host HOST]\fR +Install an initial IPA server on the given host, or on the configured master +if \-\-host is not given. + +.TP +\fBipa\-test\-task install\-replica [\-\-master MASTER] HOST\fR +Install an IPA replica on the given host. +It is initialized from the IPA server given by \-\-master, or from the +configured master if \-\-master is not given. + +.TP +\fBipa\-test\-task install\-client [\-\-master MASTER] HOST\fR +Install an IPA client on the given host. +It is initialized from the IPA server given by \-\-master, or from the +configured master if \-\-master is not given. + +.TP +\fBipa\-test\-task connect\-replica HOST1 HOST2\fR +Create a replication agreement between two given replicas. + +.TP +\fBipa\-test\-task disconnect\-replica HOST1 HOST2\fR +Remove a replication agreement between two given replicas. + +.TP +\fBipa\-test\-task uninstall\-server [HOST [HOST ...]]\fR +Uninstall an IPA server (master or replica) on the given host(s), and +restore the host(s) to the state before installation. +If no host is given, uninstalls all configured masters and replicas. +If no server is installed on a host, does nothing on that host. + +.TP +\fBipa\-test\-task uninstall\-client [HOST [HOST ...]]\fR +Uninstall an IPA client on the given host(s), and restore the host(s) to the +state before installation. +If no host is given, uninstalls all configured clients. +If no client is installed on a host, does nothing on that host. + +.TP +\fBipa\-test\-task uninstall\-all\fR +Uninstall IPA from all configured master, replica and client hosts. +Equivalent to running uninstall\-server and uninstall\-client without +arguments. + +.TP +\fBipa\-test\-task cleanup [HOST [HOST ...]]\fR +Restore system configuration (such as /etc/resolv.conf) on the given hosts +to a state before installation. +If no hosts are given, clean up all configured hosts. +This functionality is included in the uninstall\-* subcommands and is rarely +useful alone. + +.TP +\fBipa\-test\-task install-topo [\-\-skip\-master] [\-\-skip\-clients] [\-\-master M] [\-\-replicas R1 [R2...]] [\-\-clients C1 [C2 ...]] TOPO\fR +Install a number of FreeIPA servers and clients in the given topology. +Use the list\-topos subcommand for a list of available topologies. + +Unless \-\-skip\-master is given, an initial server is installed on the host +given by \-\-master, or on the configured master if \-\-master is missing. + +Replicas are installed according to the selected topology on hosts given by +\-\-replicas, or on all configured replicas if that option is not given. + +Unless \-\-skip\-clients is given, clients are installed on hosts given by +\-\-clients, or on all configured clients if \-\-clients is not given. +Servers used for client installation are selected in a round-robin fashion. + +.TP +\fBipa\-test\-task list-topos\fR +List the topologies available for the install-topo subcommand. + +.SH "EXIT STATUS" +0 if the command was successful + +nonzero if an error occurred + +.SH "REFERENCES" +A full description of the FreeIPA integration testing framework is available at +http://www.freeipa.org/page/V3/Integration_testing