[doc] add ldap schema

doc/ldap.rst

@@ -224,6 +224,7 @@ According to :file:`ldapvi` this is the domain schema (on YunoHost 2.7):
     objectClass: top
     virtualdomain: domain.com
 
+
 Updating LDAP data
 ==================
 

doc/ldap_graph.dot

@@ -0,0 +1,33 @@
+## this schema has been generated using the ldif2dot script found here http://marcin.owsiany.pl/ldif2dot-page
+## the ldapsearch query is: ldapsearch -x -b 'dc=yunohost,dc=org'
+## shape=box has been added everywhere by hand
+
+strict digraph "<stdin>" {
+  rankdir=LR
+  n0 [shape=box,label="dn: dc=yunohost,dc=org\lobjectClass: dcObject\lobjectClass: organization\lo: yunohost.org\ldc: yunohost\l"]
+  n1 [shape=box,label="dn: cn=admin,dc=yunohost,dc=org\lgidNumber: 1007\lcn: admin\lhomeDirectory: /home/admin\lobjectClass: organizationalRole\lobjectClass: posixAccount\lobjectClass: simpleSecurityObject\lloginShell: /bin/bash\ldescription: LDAP Administrator\luidNumber: 1007\luid: admin\l"]
+  n0->n1
+  n2 [shape=box,label="dn: ou=domains,dc=yunohost,dc=org\lobjectClass: organizationalUnit\lou: domains\l"]
+  n0->n2
+  n3 [shape=box,label="dn: ou=groups,dc=yunohost,dc=org\lobjectClass: organizationalUnit\lou: groups\l"]
+  n0->n3
+  n4 [shape=box,label="dn: ou=sudo,dc=yunohost,dc=org\lobjectClass: organizationalUnit\lou: sudo\l"]
+  n0->n4
+  n5 [shape=box,label="dn: ou=apps,dc=yunohost,dc=org\lobjectClass: organizationalUnit\lou: apps\l"]
+  n0->n5
+  n6 [shape=box,label="dn: ou=users,dc=yunohost,dc=org\lobjectClass: organizationalUnit\lou: users\l"]
+  n0->n6
+  n7 [shape=box,label="dn: cn=admins,ou=groups,dc=yunohost,dc=org\lobjectClass: posixGroup\lmemberUid: admin\lgidNumber: 4001\lcn: admins\l"]
+  n3->n7
+  n8 [shape=box,label="dn: cn=sftpusers,ou=groups,dc=yunohost,dc=org\lobjectClass: posixGroup\lgidNumber: 4002\lcn: sftpusers\lmemberUid: admin\lmemberUid: neutrinet\lmemberUid: alice\lmemberUid: bob\l"]
+  n3->n8
+  n9 [shape=box,label="dn: cn=admin,ou=sudo,dc=yunohost,dc=org\lcn: admin\lsudoCommand: ALL\lsudoUser: admin\lobjectClass: sudoRole\lsudoOption: !authenticate\lsudoHost: ALL\l"]
+  n4->n9
+  n10 [shape=box,label="dn: virtualdomain=domain.com,ou=domains,dc=yunohost,dc=org\lobjectClass: mailDomain\lvirtualdomain: domain.com\l"]
+  n2->n10
+  n11 [shape=box,label="dn: uid=example_admin_user,ou=users,dc=yunohost,dc=org\luid: example_admin_user\lobjectClass: mailAccount\lobjectClass: inetOrgPerson\lobjectClass: posixAccount\lloginShell: /bin/false\luidNumber: 80833\lmaildrop: example_admin_user\lcn: firstname lastname\ldisplayName: firstname lastname\lmailuserquota: 0\lgidNumber: 80833\lsn: lastname\lhomeDirectory: /home/example_admin_user\lmail: example_admin_user@domain.com\lmail: root@domain.com\lmail: admin@domain.com\lmail: webmaster@domain.com\lmail: postmaster@domain.com\lgivenName: firstname\l"]
+  n6->n11
+  n12 [shape=box,label="dn: uid=alice,ou=users,dc=yunohost,dc=org\luid: alice\lobjectClass: mailAccount\lobjectClass: inetOrgPerson\lobjectClass: posixAccount\luidNumber: 41580\lmaildrop: alice\lcn: alice pouet\ldisplayName: alice pouet\lmailuserquota: 0\lgidNumber: 41580\lsn: pouet\lhomeDirectory: /home/alice\lmail: alice@ynh.local\lgivenName: alice\lloginShell: /bin/bash\l"]
+  n6->n12
+}
+

doc/ldapsearch.result

@@ -0,0 +1,140 @@
+# extended LDIF
+#
+# LDAPv3
+# base <dc=yunohost,dc=org> with scope subtree
+# filter: (objectclass=*)
+# requesting: ALL
+#
+
+# yunohost.org
+dn: dc=yunohost,dc=org
+objectClass: top
+objectClass: dcObject
+objectClass: organization
+o: yunohost.org
+dc: yunohost
+
+# admin, yunohost.org
+dn: cn=admin,dc=yunohost,dc=org
+gidNumber: 1007
+cn: admin
+homeDirectory: /home/admin
+objectClass: organizationalRole
+objectClass: posixAccount
+objectClass: simpleSecurityObject
+loginShell: /bin/bash
+description: LDAP Administrator
+uidNumber: 1007
+uid: admin
+
+# domains, yunohost.org
+dn: ou=domains,dc=yunohost,dc=org
+objectClass: organizationalUnit
+objectClass: top
+ou: domains
+
+# groups, yunohost.org
+dn: ou=groups,dc=yunohost,dc=org
+objectClass: organizationalUnit
+objectClass: top
+ou: groups
+
+# sudo, yunohost.org
+dn: ou=sudo,dc=yunohost,dc=org
+objectClass: organizationalUnit
+objectClass: top
+ou: sudo
+
+# apps, yunohost.org
+dn: ou=apps,dc=yunohost,dc=org
+objectClass: organizationalUnit
+objectClass: top
+ou: apps
+
+# users, yunohost.org
+dn: ou=users,dc=yunohost,dc=org
+objectClass: organizationalUnit
+objectClass: top
+ou: users
+
+# admins, groups, yunohost.org
+dn: cn=admins,ou=groups,dc=yunohost,dc=org
+objectClass: posixGroup
+objectClass: top
+memberUid: admin
+gidNumber: 4001
+cn: admins
+
+# sftpusers, groups, yunohost.org
+dn: cn=sftpusers,ou=groups,dc=yunohost,dc=org
+objectClass: posixGroup
+objectClass: top
+gidNumber: 4002
+cn: sftpusers
+memberUid: admin
+memberUid: neutrinet
+memberUid: alice
+memberUid: bob
+
+# admin, sudo, yunohost.org
+dn: cn=admin,ou=sudo,dc=yunohost,dc=org
+cn: admin
+sudoCommand: ALL
+sudoUser: admin
+objectClass: sudoRole
+objectClass: top
+sudoOption: !authenticate
+sudoHost: ALL
+
+# domain.com, domains, yunohost.org
+dn: virtualdomain=domain.com,ou=domains,dc=yunohost,dc=org
+objectClass: mailDomain
+objectClass: top
+virtualdomain: domain.com
+
+# example_admin_user, users, yunohost.org
+dn: uid=example_admin_user,ou=users,dc=yunohost,dc=org
+uid: example_admin_user
+objectClass: mailAccount
+objectClass: inetOrgPerson
+objectClass: posixAccount
+loginShell: /bin/false
+uidNumber: 80833
+maildrop: example_admin_user
+cn: firstname lastname
+displayName: firstname lastname
+mailuserquota: 0
+gidNumber: 80833
+sn: lastname
+homeDirectory: /home/example_admin_user
+mail: example_admin_user@domain.com
+mail: root@domain.com
+mail: admin@domain.com
+mail: webmaster@domain.com
+mail: postmaster@domain.com
+givenName: firstname
+
+# alice, users, yunohost.org
+dn: uid=alice,ou=users,dc=yunohost,dc=org
+uid: alice
+objectClass: mailAccount
+objectClass: inetOrgPerson
+objectClass: posixAccount
+uidNumber: 41580
+maildrop: alice
+cn: alice pouet
+displayName: alice pouet
+mailuserquota: 0
+gidNumber: 41580
+sn: pouet
+homeDirectory: /home/alice
+mail: alice@ynh.local
+givenName: alice
+loginShell: /bin/bash
+
+# search result
+search: 2
+result: 0 Success
+
+# numResponses: 21
+# numEntries: 20

doc/ldif2dot-0.1.py

@@ -0,0 +1,153 @@
+#!/usr/bin/python
+# A simple script to convert an LDIF file to DOT format for drawing graphs.
+# Copyright 2009 Marcin Owsiany <marcin@owsiany.pl>
+#
+# 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 2 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, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""A simple script to convert an LDIF file to DOT format for drawing graphs.
+
+So far it only supports the most basic form of entry records: "attrdesc: value".
+In particular line continuations, BASE64 or other encodings, change records,
+include statements, etc...  are not supported.
+
+Example usage, assuming your DIT's base is dc=nodomain:
+
+ldapsearch -x -b 'dc=nodomain' | \\
+  ldif2dot | \\
+  dot -o nodomain.png -Nshape=box -Tpng /dev/stdin
+
+"""
+
+
+import sys
+
+
+class Element(object):
+    """Represents an LDIF entry."""
+
+    def __init__(self):
+        """Initializes an object."""
+        self.attributes = []
+
+    def __repr__(self):
+        """Returns a basic state dump."""
+        return 'Element' + str(self.index) + str(self.attributes)
+
+    def add(self, line):
+        """Adds a line of input to the object.
+
+        Args:
+         - line: a string with trailing newline stripped
+
+        Returns: True if this object is ready for processing (i.e. a separator
+        line was passed). Otherwise returns False. Behaviour is undefined if
+        this method is called after a previous invocation has returned True.
+        """
+
+        def _valid(line):
+            return line and not line.startswith('#')
+
+        def _interesting(line):
+            return line != 'objectClass: top'
+
+        if self.is_valid() and not _valid(line):
+            return True
+        if _valid(line) and _interesting(line):
+            self.attributes.append(line)
+        return False
+
+    def is_valid(self):
+        """Indicates whether a valid entry has been read."""
+        return len(self.attributes) != 0 and self.attributes[0].startswith('dn: ')
+
+    def dn(self):
+        """Returns the DN for this entry."""
+        if self.attributes[0].startswith('dn: '):
+            return self.attributes[0][4:]
+        else:
+            return None
+
+    def edge(self, dnmap):
+        """Returns a text represenation of a grapsh edge.
+
+        Finds its parent in provided dnmap (dictionary mapping dn names to
+        Element objects) and returns a string which declares a DOT edge, or an
+        empty string, if no parent was found.
+        """
+        dn_components = self.dn().split(',')
+        for i in range(1, len(dn_components) + 1):
+            parent = ','.join(dn_components[i:])
+            if parent in dnmap:
+                return '  n%d->n%d\n' % (dnmap[parent].index, self.index)
+        return ''
+
+    def dot(self, dnmap):
+        """Returns a text representation of the node and perhaps its parent edge.
+
+        Args:
+         - dnmap: dictionary mapping dn names to Element objects
+        """
+        return '  n%d [label="%s\\l"]\n%s' % (self.index, '\\l'.join(self.attributes), self.edge(dnmap))
+
+
+class Converter(object):
+    """An LDIF to DOT converter."""
+
+    def __init__(self):
+        """Initializes the object."""
+        self.elements = []
+        self.dnmap = {}
+
+    def _append(self, e):
+        """Adds an element to internal list and map.
+
+        First sets it up with an index in the list, for node naming.
+        """
+        index = len(self.elements)
+        e.index = index
+        self.elements.append(e)
+        self.dnmap[e.dn()] = e
+
+    def parse(self, file, name):
+        """Reads the given file into memory.
+
+        Args:
+         - file: an object which yields text lines on iteration.
+         - name: a name for the graph
+
+        Returns a string containing the graph in DOT format.
+        """
+        e = Element()
+        for line in file:
+            line = line.rstrip()
+            if e.add(line):
+                self._append(e)
+                e = Element()
+        if e.is_valid():
+            self._append(e)
+        return ('strict digraph "%s" {\n  rankdir=LR\n%s}\n'
+            % (name, ''.join([e.dot(self.dnmap) for e in self.elements])))
+
+
+if __name__ == '__main__':
+    if len(sys.argv) > 2:
+        raise 'Expected at most one argument.'
+    elif len(sys.argv) == 2:
+        name = sys.argv[1]
+        file = open(sys.argv[1], 'r')
+    else:
+        name = '<stdin>'
+        file = sys.stdin
+    print Converter().parse(file, name)