Master Controller/Software

Download esctl software

• apt-get install git
• mkdir esctl
• cd esctl
• git archive --remote=ssh://username@giles.northenden.ninja.org.uk/data/code/git/esctl master server/trunk/controller | tar xv --strip-components=3 -f -
• git archive --remote=ssh://username@giles.northenden.ninja.org.uk/data/code/git/esctl master server/trunk/schema | tar xv --strip-components=2 -f -

Configure LDAP

If you are using [Netscape/Fedora/CentOS/389] Directory Server

• cd esctl/schema/
• cp -p 70esctl.ldif /etc/ldap/schema/
• vi /usr/share/slapd/slapd.conf
  • include /etc/ldap/schema/70esctl.ldif

If you are using Debian

• sudo apt-get install slapd ldap-utils

It will ask you for the root password, but no other information. So, reconfigure the LDAP server as follows

• sudo dpkg-reconfigure --force slapd
  • Do not omit initial configuration
  • DNS domain name: customername.hosted.esctl.co.uk
  • Organization name: customername
  • Administrator password: ****
  • Database backend to use: MDB (if available), else HDB
  • Remove database when slapd is purged? Yes (??!!)
  • Move old files out of the way: Yes
  • Allow LDAPv2 protocol?: No

• sudo /etc/init.d/slapd restart

Add esctl schema extension

• mkdir ~/schemaconv
• cd ~/schemaconv
• cp -p ~/esctl/schema/70esctl.schema .
• touch empty

Now create a config file to generate the appropriate LDIF from the supplied .schema file. The earlier includes are present to ensure that the output LDIF file has the prefix of {4}, which ensures it is loaded 5th by the LDAP server (so that any pre-requisites are present by the time it loads). Check the /etc/ldap/slapd.d/cn\=config/cn\=schema/ directory to make sure this will be correct.

• vi convert.conf

include /home/pi/schemaconv/empty
include /home/pi/schemaconv/empty
include /home/pi/schemaconv/empty
include /home/pi/schemaconv/empty
include /home/pi/schemaconv/70esctl.schema

(Change /home/pi to your own home directory)

Your schemaconv directory should look something like this:

~/schemaconv# ls -l
total 16
-rw-r--r-- 1 root root 2497 Nov 20 19:01 70esctl.schema
-rw-r--r-- 1 root root  162 Nov 20 18:59 convert.conf
-rw-r--r-- 1 root root    0 Nov 20 18:56 empty

Next, create the LDIF file using the slaptest utility:

• slaptest -f convert.conf -F ~/schemaconv

config file testing succeeded

Move the file into place and restart the LDAP server:

• sudo cp -p ~/schemaconv/cn=config/cn=schema/cn={4}70esctl.ldif /etc/ldap/slapd.d/cn\=config/cn\=schema/
• sudo chown openldap /etc/ldap/slapd.d/cn\=config/cn\=schema/cn={4}70esctl.ldif
• sudo service slapd restart

Active Directory notes

• There is an installer for schema extensions; this is in the form of a .cmd file that must be run from the same directory as the accompanying LDIFs.

If you are using Samba as an Active Directory domain controller

• The user you run as, may need to be added as a member of the 'Schema Admins' group
• You may need to add the following to smb.conf:

 dsdb:schema update allowed = true

Note that there is a bug in earlier versions of Samba 4, if you are using this as an Active Directory controller. Time/date entries are not processed correctly, so if you use Active Directory Users and Computers or ADSI Edit to populate a time/date based attribute e.g. escDateFrom, you may get an error such as "Operation failed. Error code: 0x200b The attribute syntax specified to the directory service is invalid. 000200B: objectclass_attrs: attribute 'escDateFrom' on entry 'ET=xxx,OU=xxx,DC=xxx' contains at least one invalid value!"

To set up the tree and populate with user information

• Create the esctl tree in Active Directory first, using Active Directory Users and Computers. (Create Organisational Unit for ‘esctl’, then OUs for ‘readers’ and ‘tokens’)

• • Remove the default ‘authenticated users’ permissions on this tree, and replace with a specific user, which should be read-only for esctl, at the top of this tree. Modify the permission for this user in Advanced so that it applies to ‘This object and all descendant objects’

• • User could for example be cn=esctl,cn=Users,dc=mydomain,dc=co,dc=uk

• • This user also needs to have 'List contents' permission for any higher level objects e.g. I needed to grant this for ou=mylocation,dc=mydomain,dc=com as my entire esctl tree is under ou=esctl,ou=mylocation,dc=mydomain,dc=com (and users are in ou=Users,ou=mylocation,dc=mydomain,dc=com

• To easily display the escuid, escgid and other information in Active Directory Users and Computers, assuming US-English locale (409), follow the guide here and add the following to extraColumns of CN=organizationalUnit-Display,CN=409,CN=DisplaySpecifiers of the Configuration naming context.

 escuid,esctl UID,0,-1,0
 escgid,esctl GID,0,-1,0
 escDays,Days,0,65,0
 escTimeFrom,Time From,0,-1,0
 escTimeTo,Time To,0,-1,0
 escDateFrom,Date From,0,-1,0
 escDateTo,Date To,0,-1,0
 escDoor,Door,0,-1,0

Also see Display Specifier docs here

Create standard groups & users

In a fresh OpenLDAP installation you will need to create the following standard LDAP groups, users etc:

• • ou=Special Users
  • ou=People
  • ou=Groups

dn: ou=People,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
changetype: add
objectClass: organizationalUnit
objectClass: top
ou: People

dn: ou=Groups,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
changetype: add
objectClass: organizationalUnit
objectClass: top
ou: Groups

Create a file e.g. esc-users.ldif with the entries from above (change customername & password) and add it using: sudo ldapmodify -H ldapi:/// -D "cn=admin,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk" -x -W -f ./esc-users.ldif

Add read-only access to LDAP for esctl controller

If you would like your esctl controller software to connect to your LDAP server via a read-only user, rather than using the LDAP admin user, you first need to add a ESCTL Controller user:

dn: ou=Special Users,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
changetype: add
objectClass: organizationalUnit
objectClass: top
ou: Special Users

dn: cn=ESCTL Controller,ou=Special Users,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
changetype: add
objectClass: simpleSecurityObject
objectClass: organizationalRole
userPassword: ********
description: ESCTL Controller
cn: ESCTL Controller

Then you can use something like the sample olc-esc-access.ldif file supplied, to tell OpenLDAP to allow the "ESCTL Controller" user to access the esctl data in LDAP:

• cd ~/esctl/schema
• cp olc-esc-access.ldif.template olc-esc-access.ldif
• vi olc-esc-access.ldif (Ensure the root DN is correct, i.e. perhaps replace CUSTOMERNAME with your customer name, and change hdb to mdb if that is what was used during installation)

Then apply the LDIF:

• ldapmodify -Y EXTERNAL -H ldapi:/// -f ./olc-esc-access.ldif

SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
modifying entry "olcDatabase={1}hdb,cn=config"

Create indexes to optimise performance

• cd ~/esctl/schema/
• ldapmodify -Y EXTERNAL -H ldapi:/// -f ./olc-db-index.ldif

Sample LDAP schema content

version: 1

dn: ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: top
objectClass: organizationalUnit
ou: esctl

dn: ou=readers,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: top
objectClass: organizationalUnit
ou: readers

dn: ou=tokens,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: top
objectClass: organizationalUnit
ou: tokens

dn: ou=1,ou=readers,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: top
objectClass: organizationalUnit
ou: 1
description: Door 1

dn: cn=Manager,ou=1,ou=readers,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: escReader
cn: Manager
escDoor: 1
escgid: esctl Manager

dn: cn=Resident,ou=1,ou=readers,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: escReader
cn: Resident
escDoor: 1
escgid: esctl Resident

dn: et=PIN:1234,ou=tokens,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: escToken
et: PIN:1234
escuid: jbloggs

dn: et=C0572A00,ou=tokens,ou=esctl,dc=customername,dc=hosted,dc=esctl,dc=co,dc=uk
objectClass: escToken
et: C15A2D03
escDateFrom: 20140128001003Z
escDateTo: 20380101000000Z
escuid: jbloggs

MySQL

You need to have the MySQL database server installed.

The script below (log.mysql) will automatically create the 'esctl' database, and within this database will create the 'log' table that is required for the controller to log any accesses.

• mysql -u root -p < ~/esctl/controller/log.mysql

You must also create a MySQL user for the controller to use when adding new log entries.

• mysql -u root -p
  • grant insert,select on esctl.log to esctl_log@localhost identified by '***********';

Local configuration

A sample configuration file is included - copy this in place and edit according to your local needs. At a minimum you will need to check the database and LDAP login details, and the LDAP Base DN.

• cp config.pm.template config.pm
• vi config.pm

System logging

esctl logs via the standard syslog mechanism, using the "local3" facility. You can redirect these log entries to a specific file as below - by default these are not saved anywhere on a Debian system.

• sudo vi /etc/rsyslog.d/esctl.conf

local3.*        /var/log/esctl

• sudo service rsyslog restart

xinetd

For the controller to operate, 'xinetd' is used. A sample configuration file is supplied - copy this into place and check that the path to esctl-node.pl is correct for your installation.

• sudo cp -p xinetd.d-esctl /etc/xinetd.d/esctl

Finally, restart xinetd to enable esctl!

• sudo service xinetd restart

Web lastlog

Optionally, you can configure a web server to serve out information on who most recently accessed doors via esctl. Make sure you secure this appropriately, via firewall and/or htaccess & password controls.

On the Raspberry Pi platform I usually use mini-httpd:

• apt-get install mini-httpd
• vi /etc/default/mini-httpd (Set START=1)
• vi /etc/mini-httpd.conf (Comment out host=localhost)

Copy the 'lastlog' web application into place, and ensure it is able to read its configuration (can be shared with esctl controller):

• mkdir /usr/share/mini-httpd/html/cgi-bin
• cp -p /root/esctl/httpd/lastlog/lastlog /usr/share/mini-httpd/html/cgi-bin/
• cp -p /root/esctl/controller/config.pm /usr/share/mini-httpd/html/cgi-bin/

Edit config.pm to remove everything other than $DB_* and the trailing 1;