On Tuesday 16 of July 2013 14:10:44 Jan Cholasta wrote:
> On 21.6.2013 11:45, Tomas Babej wrote:
> > Newly added features:
> >
> >   - options propagated to plugins
> >   - made plugin content creation more comfortable, now 3 classes of
> > output are
> >     available (debug, comment, command)
> >
> > Now pretty much everything that comes into my mind is addressed, so
> > please have a look
> > at the current implementation.
> 
> The patch needs a rebase.
> 
> +    class AdviceLogger(object):
> 
> Please don't use nested classes. If you want AdviceLogger to be 
> private-ish, you can rename it to _AdviceLogger.
> 
> Also I think AdviceLogger is a little bit misleading name, I would 
> prefer AdviceOutput or something like that.
> 

Fixed.

> Functionally the patch is OK, but I have some second thoughts about the 
> design. I'm not sure if using API plugins is truly the right thing to 
> do, as advises seem to be pretty much orthogonal to the rest of our API. 
> There are some negative side effects, such as initializing the API every 
> time ipa-advise is run, for each and every advice, which takes some 
> time, so there is a short but noticable delay.

What do you mean by that API is initialized for each and every advice?

AFAIK, the advice plugins are all imported at once, the the API is initialized.

They are imported only in the API 'advise' context, so no performance decrease
for the rest of the framework.

> What are the benefits of 
> using API plugins for this, besides code reuse? (I'm not saying this 
> must be changed, just give it some thought, using something simpler 
> might be better.)

Code reuse is one thing. Also, ability to call the IPA commands from
within the plugins is the second factor. To allow that we would have to
inicialize the API anyway.

Also some important constants which can be leveraged by the plugins are
contained in api.env namespace.

Taking into consideration that running ipa-advise is more of a 
one-time thing, I am willing to sacrifice a bit of delay in 
favour of these advantages.

Updated patch attached.

Tomas
>From d4384a2fd9991bec0aa6082046d1a87d5645add8 Mon Sep 17 00:00:00 2001
From: Tomas Babej <tba...@redhat.com>
Date: Mon, 10 Jun 2013 14:43:24 +0200
Subject: [PATCH] Provide ipa-advise tool

Provides a pluggable framework for generating configuration
scriptlets and instructions for various machine setups and use
cases.

Creates a new ipa-advise command, available to root user
on the IPA server.

Also provides an example configuration plugin,
config-fedora-authconfig.

https://fedorahosted.org/freeipa/ticket/3670
---
 freeipa.spec.in                               |   4 +
 install/tools/Makefile.am                     |   1 +
 install/tools/ipa-advise                      |  23 ++++
 install/tools/man/Makefile.am                 |   1 +
 install/tools/man/ipa-advise.1                |  44 +++++++
 ipalib/__init__.py                            |   7 +-
 ipalib/frontend.py                            |  45 +++++++
 ipalib/plugable.py                            |   2 +
 ipaserver/advise/__init__.py                  |  22 ++++
 ipaserver/advise/base.py                      | 169 ++++++++++++++++++++++++++
 ipaserver/advise/plugins/__init__.py          |  22 ++++
 ipaserver/advise/plugins/fedora_authconfig.py |  41 +++++++
 make-lint                                     |   2 +-
 setup.py                                      |   2 +
 14 files changed, 382 insertions(+), 3 deletions(-)
 create mode 100755 install/tools/ipa-advise
 create mode 100644 install/tools/man/ipa-advise.1
 create mode 100644 ipaserver/advise/__init__.py
 create mode 100644 ipaserver/advise/base.py
 create mode 100644 ipaserver/advise/plugins/__init__.py
 create mode 100644 ipaserver/advise/plugins/fedora_authconfig.py

diff --git a/freeipa.spec.in b/freeipa.spec.in
index 86de29ffc16a199e382d2f6a6ad230a76758a55c..2f241b22c3bf2fb52aef04f8d2287565190d7870 100644
--- a/freeipa.spec.in
+++ b/freeipa.spec.in
@@ -600,6 +600,7 @@ fi
 %{_sbindir}/ipa-managed-entries
 %{_sbindir}/ipactl
 %{_sbindir}/ipa-upgradeconfig
+%{_sbindir}/ipa-advise
 %{_libexecdir}/certmonger/dogtag-ipa-retrieve-agent-submit
 %{_libexecdir}/ipa-otpd
 %config(noreplace) %{_sysconfdir}/sysconfig/ipa_memcached
@@ -615,6 +616,8 @@ fi
 %dir %{python_sitelib}/ipaserver
 %dir %{python_sitelib}/ipaserver/install
 %dir %{python_sitelib}/ipaserver/install/plugins
+%dir %{python_sitelib}/ipaserver/advise
+%dir %{python_sitelib}/ipaserver/advise/plugins
 %dir %{python_sitelib}/ipaserver/plugins
 %dir %{_libdir}/ipa/certmonger
 %attr(755,root,root) %{_libdir}/ipa/certmonger/*
@@ -730,6 +733,7 @@ fi
 %{_mandir}/man8/ipa-upgradeconfig.8.gz
 %{_mandir}/man1/ipa-backup.1.gz
 %{_mandir}/man1/ipa-restore.1.gz
+%{_mandir}/man1/ipa-advise.1.gz
 
 %files server-trust-ad
 %{_sbindir}/ipa-adtrust-install
diff --git a/install/tools/Makefile.am b/install/tools/Makefile.am
index 659ce0a87a65715b5829384f939c05e7026d763f..2cf66c6dfc1c272bb423253902e7339e7d159567 100644
--- a/install/tools/Makefile.am
+++ b/install/tools/Makefile.am
@@ -23,6 +23,7 @@ sbin_SCRIPTS =			\
 	ipa-upgradeconfig	\
 	ipa-backup		\
 	ipa-restore		\
+	ipa-advise		\
 	$(NULL)
 
 EXTRA_DIST =			\
diff --git a/install/tools/ipa-advise b/install/tools/ipa-advise
new file mode 100755
index 0000000000000000000000000000000000000000..4ec3c48c7d8b24893ed39e33d3a14ae632483bfa
--- /dev/null
+++ b/install/tools/ipa-advise
@@ -0,0 +1,23 @@
+#! /usr/bin/python -E
+# Authors: Tomas Babej <tba...@redhat.com>
+#
+# Copyright (C) 2013  Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# 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 <http://www.gnu.org/licenses/>.
+#
+
+from ipaserver.advise.base import IpaAdvise
+
+IpaAdvise.run_cli()
diff --git a/install/tools/man/Makefile.am b/install/tools/man/Makefile.am
index b16d2b5c725c06d6bb92cca3449b6afa352be13d..33e8a9e4b3408cc5447c8cad9a289ddd6ae1ebd7 100644
--- a/install/tools/man/Makefile.am
+++ b/install/tools/man/Makefile.am
@@ -21,6 +21,7 @@ man1_MANS = 				\
 	ipa-managed-entries.1		\
 	ipa-backup.1			\
 	ipa-restore.1			\
+	ipa-advise.1			\
         $(NULL)
 
 man8_MANS =				\
diff --git a/install/tools/man/ipa-advise.1 b/install/tools/man/ipa-advise.1
new file mode 100644
index 0000000000000000000000000000000000000000..4c494aab90fe307bf0a2bf82677efda4b5e67e3e
--- /dev/null
+++ b/install/tools/man/ipa-advise.1
@@ -0,0 +1,44 @@
+.\" A man page for ipa-advise
+.\" 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 <http://www.gnu.org/licenses/>.
+.\"
+.\" Author: Tomas Babej <tba...@redhat.com>
+.\"
+.TH "ipa-advise" "1" "Jun 10 2013" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-advise \- Provide configurations advice for various use cases.
+.SH "SYNOPSIS"
+ipa\-advise ADVICE
+.SH "DESCRIPTION"
+Provides customized advice for various IPA configuration issues.
+.TP
+For the list of possible ADVICEs available, run the ipa\-advise with no arguments.
+.SH "OPTIONS"
+.TP
+\fB\-\-v\fR, \fB\-\-verbose\fR
+Print debugging information
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+Alias for \-\-verbose
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Output only errors
+.TP
+\fB\-\-log\-file\fR=\fIFILE\fR
+Log to the given file
+.SH "EXIT STATUS"
+0 if the command was successful
+
+1 if an error occurred
\ No newline at end of file
diff --git a/ipalib/__init__.py b/ipalib/__init__.py
index 57f78472172b614f68021aeef2ee6e240c427888..d822ba5956d6afb6ef6d88063f8359926e47016b 100644
--- a/ipalib/__init__.py
+++ b/ipalib/__init__.py
@@ -882,7 +882,7 @@ freeIPA.org:
 import os
 import plugable
 from backend import Backend
-from frontend import Command, LocalOrRemote, Updater
+from frontend import Command, LocalOrRemote, Updater, Advice
 from frontend import Object, Method, Property
 from crud import Create, Retrieve, Update, Delete, Search
 from parameters import DefaultFrom, Bool, Flag, Int, Decimal, Bytes, Str, IA5Str, Password, DNParam, DeprecatedParam
@@ -912,9 +912,12 @@ def create_api(mode='dummy'):
 
         - `frontend.Property`
 
+        - `frontend.Advice`
+
         - `backend.Backend`
     """
-    api = plugable.API(Command, Object, Method, Property, Backend, Updater)
+    api = plugable.API(Command, Object, Method, Property, Backend, Updater,
+                       Advice)
     if mode is not None:
         api.env.mode = mode
     assert mode != 'production'
diff --git a/ipalib/frontend.py b/ipalib/frontend.py
index 427f682357579b1abcef5dcc684ef644112df124..67ca7767c1b8ef8b55722d14d00af0812a48d6d4 100644
--- a/ipalib/frontend.py
+++ b/ipalib/frontend.py
@@ -1445,3 +1445,48 @@ class Updater(Method):
         )
 
         return self.execute(**options)
+
+
+class _AdviceOutput(object):
+
+    def __init__(self):
+        self.content = []
+        self.prefix = '# '
+        self.options = None
+
+    def comment(self, line):
+        self.content.append(self.prefix + line)
+
+    def debug(self, line):
+        if self.options.verbose:
+            self.comment('DEBUG: ' + line)
+
+    def command(self, line):
+        self.content.append(line)
+
+
+class Advice(Plugin):
+    """
+    Base class for advices, plugins for ipa-advise.
+    """
+
+    options = None
+    require_root = False
+    description = ''
+
+    def __init__(self):
+        super(Advice, self).__init__()
+        self.log = _AdviceOutput()
+
+    def set_options(self, options):
+        self.options = options
+        self.log.options = options
+
+    def get_info(self):
+        """
+        This method should be overriden by child Advices.
+
+        Returns a string with instructions.
+        """
+
+        raise NotImplementedError
diff --git a/ipalib/plugable.py b/ipalib/plugable.py
index aaa0dea480f092e32815c525751359f056936e3c..25698d8f5bf4a578e4c95cf56ef4ec3e573fa615 100644
--- a/ipalib/plugable.py
+++ b/ipalib/plugable.py
@@ -615,6 +615,8 @@ class API(DictProxy):
             self.import_plugins('ipaserver')
         if self.env.context in ('installer', 'updates'):
             self.import_plugins('ipaserver/install/plugins')
+        if self.env.context in ('advise'):
+            self.import_plugins('ipaserver/advise/plugins')
 
     # FIXME: This method has no unit test
     def import_plugins(self, package):
diff --git a/ipaserver/advise/__init__.py b/ipaserver/advise/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..4fdade51300db9030dc6b7aa7c6b0e8e77f93439
--- /dev/null
+++ b/ipaserver/advise/__init__.py
@@ -0,0 +1,22 @@
+# Authors: Tomas Babej <tba...@redhat.com>
+#
+# Copyright (C) 2013  Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# 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 <http://www.gnu.org/licenses/>.
+#
+
+"""
+Base subpackage for ipa-advise related code.
+"""
diff --git a/ipaserver/advise/base.py b/ipaserver/advise/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..4b6ee96f86465c85a9a24c578f20c355473a59b6
--- /dev/null
+++ b/ipaserver/advise/base.py
@@ -0,0 +1,169 @@
+#!/usr/bin/python
+# Authors: Tomas Babej <tba...@redhat.com>
+#
+# Copyright (C) 2013  Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# 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 <http://www.gnu.org/licenses/>.
+#
+
+import os
+from ipalib import api
+from ipalib.errors import ValidationError
+from ipapython import admintool
+
+
+"""
+To add configuration instructions for a new use case, define a new class that
+inherits from Advice class.
+
+You should create a plugin file for it in ipaserver/advise/plugins folder.
+
+The class can run any arbitrary code or IPA command via api.Command['command']()
+calls. It needs to override get_info() method, which returns the formatted
+advice string.
+
+>>> class sample_advice(Advice):
+>>>     description = 'Instructions for machine with SSSD 1.0 setup.'
+
+Description provided shows itself as a header and in the list of all advices
+currently available via ipa-advise.
+
+Optionally, you can require root privileges for your plugin:
+
+>>>     require_root = True
+
+The following method should be implemented in your plugin:
+
+>>>.....def get_info():
+>>>         self.log.debug('Entering execute() method')
+>>>         self.log.comment('Providing useful advice just for you')
+>>>         self.log.command('yum update sssd -y')
+
+As you can see, Advice's log has 3 different levels. Debug lines are printed
+out with '# DEBUG:' prefix if --verbose had been used. Comment lines utilize
+'# ' prefix and command lines are printed raw.
+
+As a result, you can redirect the advice's output directly to a script file.
+
+# ipa-advise sample-advice > script.sh
+# ./script.sh
+
+Important! Do not forget to register the class to the API.
+
+>>> api.register(sample_advice)
+"""
+
+
+class IpaAdvise(admintool.AdminTool):
+    """
+    Admin tool that given systems's configuration provides instructions how to
+    configure the systems for various use cases.
+    """
+
+    command_name = 'ipa-advise'
+    usage = "%prog ADVICE"
+    description = "Provides configuration advice for various use cases. To "\
+                  "see the list of possible ADVICEs, run ipa-advise without "\
+                  "any arguments."
+
+    def __init__(self, options, args):
+        super(IpaAdvise, self).__init__(options, args)
+
+    @classmethod
+    def add_options(cls, parser):
+        super(IpaAdvise, cls).add_options(parser)
+
+    def validate_options(self):
+        super(IpaAdvise, self).validate_options(needs_root=False)
+
+        if len(self.args) > 1:
+            raise self.option_parser.error("You can only provide one "
+                                           "positional argument.")
+
+    def log_success(self):
+        pass
+
+    def print_config_list(self):
+        self.print_header('List of available advices')
+
+        max_keyword_len = max((len(keyword) for keyword in api.Advice))
+
+        for keyword in api.Advice:
+            advice = getattr(api.Advice, keyword, '')
+            description = getattr(advice, 'description', '')
+            keyword = keyword.replace('_', '-')
+
+            # Compute the number of spaces needed for the table to be aligned
+            offset = max_keyword_len - len(keyword)
+            print("    {key} {off}: {desc}".format(key=keyword,
+                                                   desc=description,
+                                                   off=' ' * offset))
+
+    def print_header(self, header, print_shell=False):
+        header_size = len(header)
+
+        prefix = ''
+        if print_shell:
+            prefix = '# '
+            print '#!/bin/sh'
+
+        # Do not print out empty header
+        if header_size > 0:
+            print(prefix + '-' * (header_size - len(prefix)))
+            print(prefix + header)
+            print(prefix + '-' * (header_size - len(prefix)))
+
+    def print_advice(self, keyword):
+        advice = getattr(api.Advice, keyword, None)
+
+        # Ensure that Configuration class for given --setup option value exists
+        if advice is None:
+            raise ValidationError(
+                name="advice",
+                error="No instructions are available for '{con}'. "
+                      "See the list of available configuration "
+                      "by invoking the ipa-advise command with no argument."
+                      .format(con=keyword.replace('_', '-')))
+
+        # Check whether root privileges are needed
+        if advice.require_root and os.getegid() != 0:
+            raise admintool.ScriptError(
+                'Must be root to get advice for {adv}'
+                .format(adv=keyword.replace('_', '-')), 1)
+
+        # Print out nicely formatted header
+        self.print_header(advice.description, print_shell=True)
+
+        # Set options so that plugin can use verbose/quiet options
+        advice.set_options(self.options)
+
+        # Print out the actual advice
+        advice.get_info()
+        for line in advice.log.content:
+            print line
+
+    def run(self):
+        super(IpaAdvise, self).run()
+
+        api.bootstrap(in_server=False, context='advise')
+        api.finalize()
+
+        # With no argument, print the list out and exit
+        if not self.args:
+            self.print_config_list()
+            return
+        else:
+            keyword = self.args[0].replace('-', '_')
+            self.print_advice(keyword)
diff --git a/ipaserver/advise/plugins/__init__.py b/ipaserver/advise/plugins/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..2d561b41ef321b500526848024f704ce462621fd
--- /dev/null
+++ b/ipaserver/advise/plugins/__init__.py
@@ -0,0 +1,22 @@
+# Authors: Tomas Babej <tba...@redhat.com>
+#
+# Copyright (C) 2013  Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# 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 <http://www.gnu.org/licenses/>.
+#
+
+"""
+Provides a separate api for ipa-advise plugins.
+"""
diff --git a/ipaserver/advise/plugins/fedora_authconfig.py b/ipaserver/advise/plugins/fedora_authconfig.py
new file mode 100644
index 0000000000000000000000000000000000000000..915877db16e08bbaea498910dc04e756b77957da
--- /dev/null
+++ b/ipaserver/advise/plugins/fedora_authconfig.py
@@ -0,0 +1,41 @@
+# Authors: Tomas Babej <tba...@redhat.com>
+#
+# Copyright (C) 2013  Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# 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 <http://www.gnu.org/licenses/>.
+#
+
+from ipalib import api
+from ipalib.frontend import Advice
+
+
+class config_fedora_authconfig(Advice):
+    """
+    Provides client configuration instructions using authconfig.
+    """
+
+    description = 'Authconfig instructions for configuring Fedora 18/19 '\
+                  'client with IPA server without use of SSSD.'
+
+    def get_info(self):
+        self.log.debug("Hostname obtained via api.env.host")
+        self.log.comment("Run the following command as a root:")
+        template = "/sbin/authconfig --enableldap --ldapserver={server} "\
+                   "--enablerfc2307bis --enablekrb5"
+        advice = template.format(server=api.env.host)
+        self.log.command(advice)
+
+
+api.register(config_fedora_authconfig)
diff --git a/make-lint b/make-lint
index 4f3e94afe1441329238af7184c9e67fec74b642b..fd7bea2130b94f07ff3e19f8168f95fa561b50fc 100755
--- a/make-lint
+++ b/make-lint
@@ -42,7 +42,7 @@ IGNORE_PATHS = ('build', 'rpmbuild', 'dist', 'install/po/test_i18n.py',
 
 class IPATypeChecker(TypeChecker):
     NAMESPACE_ATTRS = ['Command', 'Object', 'Method', 'Property', 'Backend',
-        'Updater']
+        'Updater', 'Advice']
     LOGGING_ATTRS = ['log', 'debug', 'info', 'warning', 'error', 'exception',
         'critical']
 
diff --git a/setup.py b/setup.py
index 04b20e05bb01660e3f3c77a528e7752c690e1fc7..08a14d3a10a46a6087596abf70ecadecd6b68634 100755
--- a/setup.py
+++ b/setup.py
@@ -79,6 +79,8 @@ setup(
         'ipalib',
         'ipalib.plugins',
         'ipaserver',
+        'ipaserver.advise',
+        'ipaserver.advise.plugins',
         'ipaserver.plugins',
         'ipaserver.install',
         'ipaserver.install.plugins',
-- 
1.8.3.1

_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel

Reply via email to