Extending FreeIPA

FreeIPA is an integrated security information management solution. There is a common framework written in Python to command LDAP server provided by a 389-ds project, certificate services of a Dogtag project, and a MIT Kerberos server, as well as configuring various other services typically used to maintain integrity of an enterprise environment, like DNS and time management (NTP). The framework is written in Python, runs at a server side, and provides access via command line tools or web-based user interface.

As core parts of the framework are implemented as pluggable modules, it is possible to extend FreeIPA on multiple levels. This document attempts to present general ideas and ways to make use of most of extensibility points in FreeIPA.

For information management solutions extensibility could mean multiple things. Information objects that are managed could be extended themselves or new objects could be added. New operations on existing objects might become needed or certain aspects of an object should be hidden in a specific environment. All these tasks may require quite different approaches to implement.

Following chapters will cover high-level design of FreeIPA and dive into details of its core framework. Knowledge of Python programming language basics is required. Understanding LDAP concepts is desirable, though it is not required for simple extensions as FreeIPA attempts to provide sufficient mapping of LDAP concepts onto less complex structures and Python objects, lowering a barrier to fine tune FreeIPA for the specific use cases.

FreeIPA core is written in Python programming language. The data is stored in LDAP database, and client-server paradigm is used for managing it. A FreeIPA server instance runs its own LDAP database, provided by 389-ds project (formerly Fedora Directory Server). A single instance of LDAP database corresponds to the single FreeIPA domain. Access to all information stored in the database is provided via FreeIPA server core which is run as a simple WSGI application which uses XML-RPC and JSON to exchange requests with its own clients.

Multiple replicas of the FreeIPA instance can be created on different servers, they are managed with the help of replication mechanisms of 389-ds directory server.

As LDAP database is used for data storage, LDAP's Access Control Model is used to provide privilege separation and Kerberos tickets are used to pass-through assertion of authenticity. As Kerberos server is using the same LDAP database instance, use of Kerberos tickets allows to perform operations against the database on the server if a client is capable to forward such tickets via communication channels selected for the operation.

When FreeIPA client connects to FreeIPA server, a Kerberos ticket is forwarded to the server and operations against LDAP database are performed under identity authenticated when the ticket was issued. As LDAP database also uses Kerberos to establish identity of a client, Access Control Information attributes can be used to limit what entries could be accessed and what operations could be performed.

The approach allows to delegate operations from a FreeIPA client to the FreeIPA server and in general gives FreeIPA server ability to interact with any Kerberos-aware service on behalf of the client. It also allows to keep FreeIPA client side implementation relatively light-weight: all it needs to do is to be able to forward Kerberos ticket, process XML-RPC or JSON, and present resulting responses to the user.

Besides run-time core, FreeIPA includes few configuration tools. These tools are split between server and client. Server-side tools are used when an instance of FreeIPA server is set up and configured, while client-side tools are used to configure client systems. While the server tools are used to configure LDAP database, put proper schema definitions in use, create Kerberos domain, Certificate Authority and configure all corresponding services, client side is more limited to configure PAM/NSS modules to work against FreeIPA server, and make sure that appropriate information about the client host is recorded in FreeIPA databases.

FreeIPA core defines few fundamentals. These are managed objects, their properties, and methods to apply actions to the objects. Methods, in turn, are commands that are associated with a specific object. Additionally, there are commands that do not have directly associated objects and may perform actions over few of those. Objects are stored using data store represented by a back end, and one of most useful back ends is LDAP store back end.

Altogether, set of Object, Property, Method, Command, and Backend instances represent application programming interface, API, of FreeIPA core framework.

In Python programming language object oriented support is implemented using a fairly simple concept that allows to modify instances in place, extending or removing their properties and methods. While this concept is highly useful, in security-oriented frameworks ability to lock down and trace origins of changes is also important. FreeIPA core attempts to implement locking down feature by artificially making instances of foundation classes read-only after their initialization has happened. If an attempt to modify object happens after it was locked down, an exception is thrown. There are many classes following this pattern.

For example, ipalib.frontend.Command class is derived from ipalib.frontend.HasParam class that derives from ipalib.plugable.Plugin class which, in turn, is derived from ipalib.base.ReadOnly class.

As result, every command has typed parameters and can dynamically be added to the framework. At the same time, one cannot modify the properties of the command accidentally once it is instantiated. This protects from modifications and enforces true nature of the commands: they cannot have state that is carried over across multiple calls to the same command unless the state is changing globally the whole environment around.

Environment also holds information about the context of execution. The context is important part of the FreeIPA framework as it also defines which methods of the command instance are called in order to perform action. Context in itself is defined by the environment which gives means to catch and store certain information about execution. As with commands themselves, once instantiated, environment cannot be changed.

By default, for primary FreeIPA use, there are three major contexts defined: server, client, and installer/updates.

server context

plugins are registered and communicate with clients via XML-RPC and JSON listeners. They validate any arguments and options defined and then execute whatever action they supposed to perform

client context

plugins are used to validate any arguments and options they take and then forward the request to the FreeIPA server.

installer context, updates context

plugins specific to installation and update are loaded and registered. This context can be used to extend possible operations during set up of FreeIPA server.

A user may define any context they want. FreeIPA names server context as 'server'. When using the ipa command line tool the context is 'cli'. Server installation tools, in particular, 'ipa-ldap-updater', use special 'updates' context to load specialized plugins useful during update of the installed FreeIPA server.

Because these utilities use the same framework they will do the same validation, set default values, and perform other basic actions in all contexts. This can help to save a round-trip when testing for invalid data. However, for client-server communication, the server is always authoritative and can re-define what the client has sent.

age = Int('age', label='Age', default=100)
print age(10)

verbose = Flag('verbose', default=True)

names = List('names', separator=',', skipspace=True)
names_list = names(u'John Doe, John Lee, Brad Moe')
# names_list is (u'John Doe', u'John Lee', u'Brad Moe')
names = List('names', separator=',', skipspace=False)
names_list = names(u'John Doe, John Lee, Brad Moe')
# names_list is (u'John Doe', u' John Lee', u' Brad Moe')

 1:  from ipalib import api, Object
 2:  class tank(Object):
 3:      takes_params = (
 4:          StrEnum('species*', label=u'Species', doc=u'Fish species',
 5:                   values=(u'Angelfish', u'Betta', u'Cichlid', u'Firemouth')),
 6:          Float('height', label=u'Height', doc=u'height in mm', default=400.0),
 7:          Float('width', label=u'Width', doc=u'width in mm', default=400.0),
 8:          Float('depth', label=u'Depth', doc=u'Depth in mm', default=300.0)
 9:      )
10:  
11:  api.register(tank)
12:  api.finalize()
13:  print list(api.Object.tank.params)
14:  # ['species', 'height', 'width', 'depth']

class tank_create(Method):
    def execute(self, **options):
        # create new aquarium tank

api.register(tank_create)

class tank_populate(Method):
    def execute(self, **options):
        # populate the aquarium tank with fish

api.register(tank_populate)

  1:  from ipalib.plugins.baseldap import *
  2:  from ipalib import api, Str, _, ngettext
  3:  from ipalib import Command
  4:  from ipalib.plugins import privilege
  5:  
  6:  class role(LDAPObject):
  7:      """
  8:      Role object.
  9:      """
 10:      container_dn = api.env.container_rolegroup
 11:      object_name = _('role')
 12:      object_name_plural = _('roles')
 13:      object_class = ['groupofnames', 'nestedgroup']
 14:      default_attributes = ['cn', 'description', 'member', 'memberof',
 15:          'memberindirect', 'memberofindirect',
 16:      ]
 17:      attribute_members = {
 18:          'member': ['user', 'group', 'host', 'hostgroup'],
 19:          'memberof': ['privilege'],
 20:      }
 21:      reverse_members = {
 22:          'member': ['privilege'],
 23:      }
 24:      rdnattr='cn'
 25:  
 26:      label = _('Roles')
 27:      label_singular = _('Role')
 28:  
 29:      takes_params = (
 30:          Str('cn',
 31:              cli_name='name',
 32:              label=_('Role name'),
 33:              primary_key=True,
 34:          ),
 35:          Str('description',
 36:              cli_name='desc',
 37:              label=_('Description'),
 38:              doc=_('A description of this role-group'),
 39:          ),
 40:      )
 41:  
 42:  api.register(role)
 43:  
 44:  
 45:  class role_add(LDAPCreate):
 46:      __doc__ = _('Add a new role.')
 47:  
 48:      msg_summary = _('Added role "%(value)s"')
 49:  
 50:  api.register(role_add)
 51:  
 52:  
 53:  class role_del(LDAPDelete):
 54:      __doc__ = _('Delete a role.')
 55:  
 56:      msg_summary = _('Deleted role "%(value)s"')
 57:  
 58:  api.register(role_del)
 59:  
 60:  
 61:  class role_mod(LDAPUpdate):
 62:      __doc__ = _('Modify a role.')
 63:  
 64:      msg_summary = _('Modified role "%(value)s"')
 65:  
 66:  api.register(role_mod)
 67:  
 68:  
 69:  class role_find(LDAPSearch):
 70:      __doc__ = _('Search for roles.')
 71:  
 72:      msg_summary = ngettext(
 73:          '%(count)d role matched', '%(count)d roles matched', 0
 74:      )
 75:  
 76:  api.register(role_find)
 77:  
 78:  
 79:  class role_show(LDAPRetrieve):
 80:      __doc__ = _('Display information about a role.')
 81:  
 82:  api.register(role_show)
 83:  
 84:  
 85:  class role_add_member(LDAPAddMember):
 86:      __doc__ = _('Add members to a role.')
 87:  
 88:  api.register(role_add_member)
 89:  
 90:  
 91:  class role_remove_member(LDAPRemoveMember):
 92:      __doc__ = _('Remove members from a role.')
 93:  
 94:  api.register(role_remove_member)
 95:  
 96:  
 97:  class role_add_privilege(LDAPAddReverseMember):
 98:      __doc__ = _('Add privileges to a role.')
 99:  
100:      show_command = 'role_show'
101:      member_command = 'privilege_add_member'
102:      reverse_attr = 'privilege'
103:      member_attr = 'role'
104:  
105:      has_output = (
106:          output.Entry('result'),
107:          output.Output('failed',
108:              type=dict,
109:              doc=_('Members that could not be added'),
110:          ),
111:          output.Output('completed',
112:              type=int,
113:              doc=_('Number of privileges added'),
114:          ),
115:      )
116:  
117:  api.register(role_add_privilege)
118:  
119:  
120:  class role_remove_privilege(LDAPRemoveReverseMember):
121:      __doc__ = _('Remove privileges from a role.')
122:  
123:      show_command = 'role_show'
124:      member_command = 'privilege_remove_member'
125:      reverse_attr = 'privilege'
126:      member_attr = 'role'
127:  
128:      has_output = (
129:          output.Entry('result'),
130:          output.Output('failed',
131:              type=dict,
132:              doc=_('Members that could not be added'),
133:          ),
134:          output.Output('completed',
135:              type=int,
136:              doc=_('Number of privileges removed'),
137:          ),
138:      )
139:  
140:  api.register(role_remove_privilege)

As said earlier, until API instance is finalized, objects, methods, and commands can be added, removed, or modified freely. This allows to extend existing objects. Before API is finalized, we cannot address objects through the unified interface as api.Object.foo, but for almost all cases an object named foo is defined in a plugin ipalib.plugins.foo.

1. Add new parameter:

   1:  from ipalib.plugins.user import user
   2:  from ipalib import Str, _
   3:  user.takes_params += (
   4:         Str('foo',
   5:              cli_name='foo',
   6:              label=_('Foo'),
   7:         ),
   8:      )
   

2. Re-define User object label to use organisation-specific terminology in Web UI:

   1:  from ipalib.plugins.user import user
   2:  from ipalib import text
   3:  
   4:  _ = text.GettextFactory(domain='extend-ipa')
   5:  user.label = _('Staff')
   6:  user.label_singular = _('Engineer')
   

   Note that we re-defined locally _ method to use different GettextFactory. As GettextFactory is supporting a single translation domain, all new translation terms need to be placed in a separate translation domain and referred accordingly. Python rules for scoping will keep this symbol as <package>._ and as nobody imports it explicitly, it will not interfere with the framework's provided text._.

3. Assume /dev/null as default shell for all new users:

    1:  from ipalib.plugins.user import user_add
    2:  
    3:  def override_default_shell_cb(self, ldap, dn. 
    4:                                entry_attrs, attrs_list,
    5:                                *keys, **options):
    6:      if 'loginshell' in entry_attrs:
    7:          default_shell = [self.api.Object.user.params['loginshell'].default]
    8:          if entry_attrs['loginshell'] == default_shell:
    9:              entry_attrs['loginshell'] = [u'/dev/null']
   10:  
   11:  user_add.register_pre_callback(override_default_shell_cb)
   

The last example exploits a powerful feature available for every method of LDAPObject: registered callbacks.

For objects stored in LDAP database instance all methods support adding callbacks. A callback is a user-provided function that is called at certain point of execution of a method.

There are four types of callbacks:

PRE callback

called before executing the method's action. Allows to modify passed arguments, do additional validation or data transformation and specific access control beyond what is provided by the framework.

POST callback

called after executing the method's action. Allows to analyze results of the action and perform additional actions or modify output.

EXC callback

called in case execution of the method's action caused an execution error. These callbacks provide means to recover from an erroneous execution.

INTERACTIVE callback

called at a client context to allow a command to decide if additional parameters should be requested from an user. This mechanism especially useful to simplify complex interaction when there are several levels of possible scenarios depending on what was provided at a client side.

All callback types are available to any class derived from CallbackInterface class. These include all LDAP-based CRUD methods.

Callback registration methods accept a reference to callable and optionally ordering argument first (False by default) to allow the callback be executed before previously registered callbacks of this type.

CallbackInterface class provides following class methods:

register_pre_callback

registers PRE callback

register_post_callback

registers POST callback

register_exc_callback

registers EXC callback for purpose of recovering from execution errors

register_interactive_prompt_callback

registers callbacks called by the client context.

Let's look again at the last example:

 1:  from ipalib.plugins.user import user_add
 2:  
 3:  def override_default_shell_cb(self, ldap, dn. 
 4:                                entry_attrs, attrs_list, 
 5:                                *keys, **options):
 6:      if 'loginshell' in entry_attrs:
 7:          default_shell = [self.api.Object.user.params['loginshell'].default]
 8:          if entry_attrs['loginshell'] == default_shell:
 9:              entry_attrs['loginshell'] = [u'/dev/null']
10:  
11:  user_add.register_pre_callback(override_default_shell_cb)

This extension defines a pre-processing callback that accepts number of arguments:

ldap

reference to the back end to store and retrieve the object's data

dn

reference to the object data in LDAP

entry_attrs

arguments and options of the command and their values as a dictionary. All values in entry_attrs will be used for communicating with LDAP store, thus replacing values should be done with care. For details please see Python LDAP module documentation

attrs_list

list of all attributes we intend to fetch from the back end

keys

arguments of the command

options

all other unidentified parameters passed to the method

Arguments of a post-processing callback, POST, are slightly different. As action is already performed and the attributes of the entry are fetched back from the back end, there is no need to provide attrs_list:

1:  from ipalib.plugins.user import user_add
2:  def verify_shell_cb(self, ldap, dn. entry_attrs, 
3:                      *keys, **options):
4:      if 'loginshell' in entry_attrs:
5:          default_shell = [self.api.Object.user.params['loginshell'].default]
6:          if entry_attrs['loginshell'] == default_shell:
7:              # report that default shell is assigned
8:  
9:  user_add.register_post_callback(verify_shell_cb)

Execution error callback, EXC, has following signature:

1:  def user_add_error_cb(self, args, options, exc,
2:                        call_func, *call_args, **call_kwargs):
3:      return

where arguments have following meaning:

args

arguments of the original method

options

options of the original method

exc

exception object thrown by a call_func

call_func

function that was called by the method and caused the error of execution. In case of LDAP-based methods this is often ldap.add_entry() or ldap.modify_entry(), or a similar function

call_args

first argument passed to the call_func

call_kwargs

remaining arguments of call_func

Finally, interactive prompt callback receives kw argument which is a dictionary of all arguments of the command.

All callbacks are supplied with a reference to the method instance, self, unless the callback itself has an attribute called 'im_self'. As can be seen in callback examples, self reference recursively provides access to the whole FreeIPA API structure.

This approach gives complete control of existing FreeIPA methods without deep dive into details of LDAP programming even if the framework allows such a deep dive.

FreeIPA framework has two major client applications: Web UI and command line-based client tool, ipa. Web UI communicates with a FreeIPA server running WSGI application that accepts JSON-formatted requests and translates them to calls to FreeIPA plugins.

A following code in install/share/ui/wsgi.py defines FreeIPA web application:

 1:  from ipalib import api
 2:  from ipalib.config import Env
 3:  from ipalib.constants import DEFAULT_CONFIG
 4:  
 5:  # Determine what debug level is configured. We can only do this
 6:  # by reading in the configuration file(s). The server always reads
 7:  # default.conf and will also read in `context'.conf.
 8:  env = Env()
 9:  env._bootstrap(context='server', log=None)
10:  env._finalize_core(**dict(DEFAULT_CONFIG))
11:  
12:  # Initialize the API with the proper debug level
13:  api.bootstrap(context='server', debug=env.debug, log=None)
14:  try:
15:      api.finalize()
16:  except StandardError, e:
17:      api.log.error('Failed to start IPA: %s' % e)
18:  else:
19:      api.log.info('*** PROCESS START ***')
20:  
21:      # This is the WSGI callable:
22:      def application(environ, start_response):
23:          if not environ['wsgi.multithread']:
24:              return api.Backend.session(environ, start_response)
25:          else:
26:              api.log.error("IPA does not work with the threaded MPM, use the pre-fork MPM")

At line 13 we set up FreeIPA framework with server context. This means plugins are loaded and initialized from following locations:

• ipalib/plugins/ – general FreeIPA plugins, available for all contexts
• ipaserver/plugins/ – server-specific plugins, available in 'server' context

With api.finalize() call at line 15 FreeIPA framework is locked down and all components provided by plugins are registered at api name spaces: api.Object, api.Method, api.Command, api.Backend.

At this point, api name spaces become usable and our WSGI entry point, defined on lines 22 to 26 can access api.Backend.session() to generate response for WSGI request.

Web UI itself is written in JavaScript and utilizes JQuery framework. It can be split into three major parts:

communication

tools defined in ipa.js to allow talking with FreeIPA server using AJAX requests and JSON formatting

presentation

tools in facet.js, entity.js, search.js, widget.js, add.js, and details.js to give basic building blocks of Web UI

objects

actual implementation of Web UI for FreeIPA objects (user, group, host, rule, and other available objects registered at api.Object by the server side)

The code of these JavaScript files is loaded in index.html and kicked into work by webui.js where main navigation and document's onready event handler are defined. In addition, index.html imports extension.js file where all extensions to Web UI can be registered or referenced. As extension.js is loaded after all other Web UI JavaScript files but before webui.js, it can already use all tools of the Web UI.

The execution of Web UI starts with the call of IPA.init() function which does following:

1. Set up AJAX asynchronous communication via POST method using JSON format.
2. Fetches meta-data about FreeIPA methods available on the server using JSON format and makes them available as IPA.methods.
3. Fetches meta-data about FreeIPA objects available on the server using JSON format and makes them available as IPA.objects.
4. Fetches translations of messages used in the Web UI and makes them available as IPA.messages.
5. Fetches identity of the user running the Web UI, accessible as IPA.whoami.
6. Fetches FreeIPA environment specific for Web UI, accessible as IPA.env.

The communication with FreeIPA server is done using IPA.command() function. Commands created with IPA.command() can later be executed with execute() method. This separation of construction and actual execution allows to create multiple commands and combine them together in a single request. Batch requests are created with IPA.batch_command() function and command are added to them with add_command() method. In addition, FreeIPA Web UI allows to run commands concurrently with IPA.concurrent_command() function.

Web UI has following DOM structure:

	Container
background	header	navigation	content
background-header	header-logo
background-navigation	header-network-activity-indicator
background-left	loggedinas
background-right

Container div is a top-level one, it includes background, header, navigation, content divs. These divs and their parts can be manipulated from the JavaScript code to represent the UI. However, FreeIPA gives an easier way to accomplish this.

 1:  IPA.netgroup = {};
 2:  
 3:  IPA.netgroup.entity = function(spec) {
 4:      var that = IPA.entity(spec);
 5:      that.init = function(params) {
 6:          params.builder.search_facet({
 7:              columns: [
 8:                  'cn',
 9:                  'description'
10:              ]
11:          }).
12:          details_facet({
13:              sections: [
14:                  {
15:                      name: 'identity',
16:                      fields: [
17:                          'cn',
18:                          {
19:                              factory: IPA.textarea_widget,
20:                              name: 'description'
21:                          },
22:                          'nisdomainname'
23:                      ]
24:                  }
25:              ]
26:          }).
27:          association_facet({
28:              name: 'memberhost_host',
29:              facet_group: 'member'
30:          }).
31:          association_facet({
32:              name: 'memberhost_hostgroup',
33:              facet_group: 'member'
34:          }).
35:          association_facet({
36:              name: 'memberuser_user',
37:              facet_group: 'member'
38:          }).
39:          association_facet({
40:              name: 'memberuser_group',
41:              facet_group: 'member'
42:          }).
43:          association_facet({
44:              name: 'memberof_netgroup',
45:              associator: IPA.serial_associator
46:          }).
47:          standard_association_facets().
48:          adder_dialog({
49:              fields: [
50:                  'cn',
51:                  {
52:                      factory: IPA.textarea_widget,
53:                      name: 'description'
54:                  }
55:              ]
56:          });
57:      };
58:  
59:      return that;
60:  };
61:  
62:  IPA.register('netgroup', IPA.netgroup.entity);

 1:  IPA.tank = {};
 2:  IPA.tank.entity = function(spec) {
 3:      var that = IPA.entity(spec);
 4:      that.init = function(params) {
 5:          details_facet({
 6:              sections: [
 7:                  {
 8:                       name: 'identity',
 9:                       fields: [
10:                           'species', 'height', 'width', 'depth'
11:                       ]
12:                  }
13:              ]
14:          }).
15:          standard_association_facets().
16:          adder_dialog({
17:              fields: [
18:                  'species', 'height', 'width', 'depth'
19:              ]
20:          });
21:      };
22:  };
23:  
24:  IPA.register('tank', IPA.tank.entity);

As an alternative to Web UI, FreeIPA server can be controlled via command-line interface provided by the ipa utility. This utility is operating under 'client' context and looks even simpler than Web UI's wsgi.py:

1:  import sys
2:  from ipalib import api, cli
3:  
4:  if __name__ == '__main__':
5:      cli.run(api)

cli.run() is the central running point defined in ipalib/cli.py:

 1:  # <cli.py code> ....
 2:  cli_plugins = (
 3:      cli,
 4:      textui,
 5:      console,
 6:      help,
 7:      show_mappings,
 8:  )
 9:  
10:  def run(api):
11:      error = None
12:      try:
13:          (options, argv) = api.bootstrap_with_global_options(context='cli')
14:          for klass in cli_plugins:
15:              api.register(klass)
16:          api.load_plugins()
17:          api.finalize()
18:          if not 'config_loaded' in api.env:
19:              raise NotConfiguredError()
20:          sys.exit(api.Backend.cli.run(argv))
21:      except KeyboardInterrupt:
22:          print ''
23:          api.log.info('operation aborted')
24:      except PublicError, e:
25:          error = e
26:      except StandardError, e:
27:          api.log.exception('%s: %s', e.__class__.__name__, str(e))
28:          error = InternalError()
29:      if error is not None:
30:          assert isinstance(error, PublicError)
31:          api.log.error(error.strerror)
32:          sys.exit(error.rval)

As with WSGI, api is bootstraped, though with a client context and using global options from /etc/ipa/default.conf, and command line arguments. In addition to common plugins available in ipalib/plugins, cli.py adds few command-line specific classes defined in the module itself:

cli

a backend for executing from command line interface which does translation of command line option names, basic verification of commands and fallback to show help messages with help command, execution of the command, and translation of the output to command-line friendly format if this is defined for the command.

textui

a backend to nicely format output to stdout which handles conversion from binary to base64, prints text word-wrapped to the terminal width, formats returned complex values so that they can be easily understood by a human being.

>>> entry = {'name' : u'Test example', 'age' : u'100'}
>>> api.Backend.textui.print_entry(entry)
  age: 100
  name: Test example

console

starts interactive Python console with FreeIPA commands

help

generates help for every command and method of FreeIPA and structures it into sections according to the registered FreeIPA objects.

>>> api.Command.help(u'user-show')
Purpose: Display information about a user.
Usage: ipa [global-options] user-show LOGIN [options]

Options:
-h, --help  show this help message and exit
--rights    Display the access rights of this entry (requires --all). See 
            ipa man page for details.
--all       Retrieve and print all attributes from the server. Affects 
            command output.
--raw       Print entries as stored on the server. Only affects output
            format.

show_mappings

displays mappings between command's parameters and LDAP attributes:

>>> api.Command.show_mappings(command_name=u"role-find")
Parameter : LDAP attribute
========= : ==============
name      : cn
desc      : description
timelimit : timelimit?
sizelimit : sizelimit?

 1:  from ipalib import frontend
 2:  from ipalib import output
 3:  from ipalib import _, ngettext
 4:  from ipalib import api
 5:  import time
 6:  
 7:  __doc__ = _("""
 8:  Local extensions to FreeIPA commands
 9:  """)
10:  
11:  class timed_ping(frontend.Command):
12:      __doc__ = _('Ping remote FreeIPA server and measure round-trip')
13:  
14:      has_output = (
15:                            output.summary,
16:                            )
17:      def run(self):
18:          t1 = time.time()
19:          result = self.api.Command.ping()
20:          t2 = time.time()
21:          summary = u"""Round-trip to the server is %f ms.
22:  Server response is %s"""
23:          return dict(summary=summary % ((t2-t1)*1000.0, result['summary']))
24:  
25:  api.register(timed_ping)

$ ipa timed-ping
-----------------------------------------------------------------------------
Round-trip to the server is 286.306143 ms.
Server response is IPA server version 2.1.3GIT8a254ca. API version 2.13
-----------------------------------------------------------------------------

Finally, it should be noted that depending on installed Python version and operating system, paths where plugins are loaded from may differ. Usually Python extensions are placed in site-packages Python sub-directory. In Fedora and RHEL distributions, this is /usr/lib/python<version>/site-packages. Thus, full path to extend-cli.py would be /usr/lib/python<version>/site-packages/ipalib/plugins/extend-cli.py.

On recent Fedora distribution, following paths are used:

Plugins	Python module prefix	File path
common	ipalib/plugins	/usr/lib/python2.7/site-packages/ipalib/plugins
server	ipaserver/plugins	/usr/lib/python2.7/site-packages/ipaserver/plugins
installer, updates	ipaserver/install/plugins	/usr/lib/python2.7/site-packages/ipaserver/install/plugins

Next table explains use of contexts in FreeIPA applications:

Context	Application	Plugins	Description
server	wsgi.py	common, server	Main FreeIPA server, server context
cli	ipa	common	Command line interface, client context
updates	ipa-ldap-updater	common, server, updates	LDAP schema updater

Originally FreeIPA was created utilizing packages available in Fedora and RHEL distributions. During configuration stages multiple system services need to be stopped and started again, scheduled to start after reboot and re-configured. In addition, when operating system utilizing security measures to harden the server setup, appropriate activities need to be done as well for preserving proper security contexts. As configuration details, service names, security features and management tools differ substantially between various GNU/Linux distributions and other operating systems, porting FreeIPA project's code to other environment has proven to be problematic.

When Fedora project has decided to migrate to systemd for services management, FreeIPA packages for Fedora needed to be updated as well, at the same time preserving support for older SystemV initialization scheme used in older releases. This prompted to develop a 'platformization' support allowing to abstract services management between different platforms.

FreeIPA 2.1.3 includes first cut of platformization work to support Fedora 16 distribution based on systemd. At the same time, there is an effort to port FreeIPA client side code to Ubuntu distributions.

Platform portability in FreeIPA means centralization of code to manage system-provided services, authentication setup, and means to manage security context and host names. It is going to be extended in future to cover other areas as well, both client- and server-side.

The code that implements platform-specific adaptation is placed under ipapython/platform. As of FreeIPA 2.1.3, there are two major "platforms" supported:

redhat

Red Hat-based distributions utilizing SystemV init scripts such as Fedora 15 and RHEL6

fedora16

as name suggests, Fedora 16 and above, are supported by this platform module. It is based on systemd system management tool and utilizes common code in ipapython/platform/systemd.py. fedora16.py contains only differentiation required to cover Fedora 16-specific implementation of systemd use, depending on changes to Dogtag, Tomcat6, and 389-ds packages.

Each platform-specific adaptation should provide few basic building blocks:

 1:  from ipapython import services as ipaservices
 2:  
 3:  auth_config = ipaservices.authconfig()
 4:  auth_config.disable("ldap").\
 5:              disable("krb5").\
 6:              disable("sssd").\
 7:              disable("sssdauth").\
 8:              disable("mkhomedir").\
 9:              add_option("update").\
10:              enable("nis").\
11:              add_parameter("nisdomain","foobar")
12:  auth_config.execute()

from ipapython import services as ipaservices
....
-    service.restart("dirsrv")
-    service.restart("krb5kdc")
-    service.restart("httpd")
+    ipaservices.knownservices.dirsrv.restart()
+    ipaservices.knownservices.krb5kdc.restart()
+    ipaservices.knownservices.httpd.restart()

export SUPPORTED_PLATFORM=fedora16
# Force re-generate of platform support
rm -f ipapython/services.py
make version-update
make IPA_VERSION_IS_GIT_SNAPSHOT=no all

# authconfig is an entry point to platform-provided AuthConfig implementation
# (instance of ipapython.platform.base.AuthConfig)
authconfig = None

# knownservices is an entry point to known platform services
# (instance of ipapython.platform.base.KnownServices)
knownservices = None

# service is a class to instantiate ipapython.platform.base.PlatformService
service = None

# restore context default implementation  that does nothing
def restore_context_default(filepath):
    return

# Restore security context for a path
# If the platform has security features where context is important, implement your own
# version in platform services
restore_context = restore_context_default

# Default implementation of backup and replace hostname that does nothing
def backup_and_replace_hostname_default(fstore, statestore, hostname):
    return

# Backup and replace system's hostname
# Since many platforms have their own way how to store system's hostname, this method must be
# implemented in platform services
backup_and_replace_hostname = backup_and_replace_hostname_default

from ipapython.platform.SUPPORTED_PLATFORM import *