How each OS handles NFSv3 and NFSv4

All Linux distros treat NFSv4 as a different filesystem. Solaris treats NFSv4 as a newer version, which is the sane, and sensible way of handling it IMO; thanks Linux…. To mount an NFSv4 filesystem in RHEL 5, you mount it the following way:

mount -t nfs4 <server>:<share> <mountpoint>

For NFSv3, you mount it the following way:

mount -t nfs <server>:<share> <mountpoint>

Solaris 10 will automatically mount an NFS share as version 4, if the server supports it, and the client is configured to support NFSv4. To check the versions supported by the server and the client, see the /etc/default/nfs configuration file. Here are the options to look for:

# Sets the minimum version of the NFS protocol that will be registered
# and offered by the server.  The default is 2.
#NFS_SERVER_VERSMIN=2

# Sets the maximum version of the NFS protocol that will be registered
# and offered by the server.  The default is 4.
#NFS_SERVER_VERSMAX=4

# Sets the minimum version of the NFS protocol that will be used by
# the NFS client.  Can be overridden by the "vers=" NFS mount option.
# The default is 2.
#NFS_CLIENT_VERSMIN=2

# Sets the maximum version of the NFS protocol that will be used by
# the NFS client.  Can be overridden by the "vers=" NFS mount option.
# If "vers=" is not specified for an NFS mount, this is the version
# that will be attempted first.  The default is 4.
#NFS_CLIENT_VERSMAX=4

Notice that by default Solaris 10 will use NFSv4 for both clients and servers.

To manually mount a filesystem as NFSv4, you mount it the following way:

mount -F nfs -o vers=4 <server>:<share> <mountpoint>

Solaris 9 doesn’t support NFSv4, only v3. To mount a filesystem as NFSv3, you mount it the following way:

mount -F nfs -o vers=3 <server>:<share> <mountpoint>

If you are familiar with automount entries, you may already see the problem.

The NFSv4 automount problem

Linux is the cause of our problem. Implementing NFSv4 as a new filesystem instead of as a higher version number means we can’t simply pass a consistent option to the automounter to specify a mount as NFSv4. Here’s an example automount entry in LDAP:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

If we want this to mount as NFSv4, we’ll need the following for RHEL 5 and above:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: -fstype=nfs4 example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

This won’t work on Solaris, as Solaris doesn’t treat NFSv4 as a separate filesystem.

Solving the problem

Creating the LDAP autofs entry

To avoid duplicating all automount entries for RHEL 4 and5, and Solaris 9 and 10, we’ll need to do some trickery on the systems and in LDAP. What we want, is for Solaris 9 and below to see the following:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: -vers=3 example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

Solaris 10 and above to see the following:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: -vers=4 example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

RHEL 4 and below to see the following:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: -fstype=nfs example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

and RHEL 5 and above to see the following:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: -fstype=nfs4 example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

Thankfully, autofs on both RHEL and Solaris supports variable substitution. We can use the following entry to achieve the above results:

dn: cn=test,nisMapName=auto_test,dc=example,dc=com
nisMapEntry: -${NFSOPT}=${NFSVER} example-server:/example/share
objectClass: nisObject
objectClass: top
nisMapName: auto_test
cn: test

The two above variables aren’t standard variables, so here’s where the trickery comes in.

Setting the autofs variables on each OS

On Solaris 9, we’ll have to modify autofs’s init script; the variables can be added to the autofs command like so:

/usr/lib/autofs automountd -D NFSOPT=vers -D NFSVER=3 < /dev/null > /dev/msglog 2>&1

Specifically the “-D NFSOPT=vers -D NFSVER=3″ portion of the line is the key portion.

On Solaris 10, the options can be added in /etc/default/autofs; simply add the following lines to the bottom of the file:

AUTOMOUNTD_ENV=NFSVER=4
AUTOMOUNTD_ENV=NFSOPT=vers

On RHEL 4 and below, the following can be added to /etc/sysconfig/autofs:

LOCALOPTIONS="-DNFSOPT=fstype -DNFSVER=nfs"

On RHEL 5 and above, the following can be added to /etc/sysconfig/autofs:

OPTIONS="-DNFSOPT=fstype -DNFSVER=nfs4"

You don’t necessarily need to use these variables; you can use any variables you want. Remember, though, if you change them, to change them all consistently.

Downsides to this approach

1. You need to configure every single client to support it
2. Every NFSv4 automount entry needs to have “-${NFSOPT}=${NFSVER}” added
3. There is no way to make Solaris clients mount some mounts as NFSv3, and others as NFSv4

The ARD service is controlled by launchd, and will restart automatically if killed. To relaunch the service, simply run the following command (you must be an admin, or root):

killall ARDAgent

I was actually planning on writing this extension, and haven’t had time to get to it. I’ve asked Pat if I can test, clean up, and maintain his extension in Wikimedia’s SVN.

After deploying the web agent, MediaWiki started parsing things incorrectly. Wiki-syntax like:

== Test ==
== Test2 ==
=== Test 3 ===

Was being corrupted, and turning into something like:

== Test ==== Test2 ===== Test3 ===

I traced it down to a conflict between the OpenSSO web agent and php-xml (dom.so specifically). I’m not sure exactly what the issue is, but removing the php-xml package from Red Hat Enterprise Linux 5 (RHEL 5) solved the parsing problem. Unfortunately, some MediaWiki extensions, like ImageMap, require php-xml.

I was able to fix the issue in MediaWiki’s configuration by telling the parser to use plain PHP arrays for temporary storage instead of PHP’s DOM. I did this by putting the following into LocalSettings.php:

$wgParserConf = array(
        'class' => 'Parser',
        'preprocessorClass' => 'Preprocessor_Hash',
);

If anyone has an idea on a better way to fix this, I’m all ears. I’d like to not have a nasty workaround like this.

This post about managing certificate trust flags in Network Security Services (NSS) databases is part of that 10%, and is the kind of thing everyone dealing with NSS should read. It is crazy that this information is missing from Mozilla’s documentation on certutil; this really makes the trust flags clear!

Please leave any open bugs/issues/changes needed in the comments.

Group restrictions and synchronization will require you to somewhat understand the LDAP structure that your AD environment is built upon. Don’t worry, this isn’t as scary as it sounds, and I’ll explain how to find all of the information you’ll require.

Prerequisites

Before you start, you must have authentication working. See part 1 of this series to enable authentication. Don’t try to get everything working at the same time. First ensure authentication is working, then enable group restrictions, then go from there.

For this article we will use the domain configured in part 1:

$wgLDAPDomainNames = array( "TESTAD" );

Group configuration

Shared group options

Telling the plugin how to map users to group members

AD stores full Distinguished Names (DN)s like cn=Ryan Lane,dc=testad,dc=example,dc=com in groups, so we’ll need to tell the plugin to use full DNs. Also, we’ll need to tell the plugin how to get the user’s DN. Place the following in LocalSettings.php:

$wgLDAPGroupUseFullDN = array( "TESTAD"=>true );
$wgLDAPBaseDNs = array( 'TESTAD' => 'dc=testad,dc=example,dc=com' );
$wgLDAPSearchAttributes = array( 'TESTAD' => 'sAMAccountName' )

Telling the plugin how to find users in groups

For the plugin to find your groups, it needs to know how to search for them. There are two methods for doing this: The first (and easiest) way to do this is to use memberOf. The second way is to tell the plugin the attribute and objectclass used by the group, and the attribute used for member of the group.

Using memberOf

Currently, the plugin cannot find the primary group of a user using memberOf. If you need to restrict groups based on user’s primary groups, do not use memberOf. To enable memberOf for AD, put the following in LocalSettings.php:

$wgLDAPGroupsUseMemberOf = array( "TESTAD" => true );

Manually configure the search

Thankfully, most (all?) AD configurations use the same attributes and objectclasses for group membership, so this is fairly straightforward. Put the following into LocalSettings.php:

//The objectclass of the groups we want to search for
$wgLDAPGroupObjectclass = array( "TESTAD"=>"group" );

//The attribute used for group members
$wgLDAPGroupAttribute = array( "TESTAD"=>"member" );

//The naming attribute of the group
$wgLDAPGroupNameAttribute = array( "TESTAD"=>"cn" );

Group restrictions

The LDAP plugin supports two types of group restriction. The first is a list of groups a user is required to be a member of (required groups), the second is a list of groups a user cannot be a member of (excluded groups). Both types of restrictions can be used simultaneously.

Required groups

To require a user to be a member of a group (such as cn=wiki-users,ou=groups,dc=testad,dc=example,dc=com), put the following into LocalSettings.php:

$wgLDAPRequiredGroups = array( "TESTAD"=> array( "cn=wiki-users,ou=groups,dc=testad,dc=example,dc=com" ) );

Excluded groups

To require a user to not be a member of a specific group (such as cn=excluded-wiki-users,ou=groups,dc=testad,dc=example,dc=com), put the following into LocalSettings.php:

$wgLDAPExcludedGroups = array( "TESTAD"=> array( "cn=excluded-wiki-users,ou=groups,dc=testad,dc=example,dc=com" ) );

Group synchronization

Group synchronization allows you to manage MediaWiki authorization using groups defined in your AD server. To enable synchronization, simply add the following to LocalSettings.php:

$wgLDAPUseLDAPGroups = array( "TESTAD"=>true );

To use LDAP groups, you’ll have to define their permissions; say for instance you have a group called “wiki-users”, you could enable edit permissions for users in that group by adding the following to LocalSettings.php:

$wgGroupPermissions['wiki-users']['edit'] = true;

If you’d like to add sysop permissions to a group called “wiki-admins”, you could put the following into LocalSettings.php:

$wgGroupPermissions['wiki-admin'] = $wgGroupPermissions['sysop'];

Overall, group synchronization is far more powerful than group restriction. See MediaWiki’s user rights documentation for more information on controlling access.

Retrieving preferences

The LDAP plugin can pull certain attributes from AD, and assign them to MediaWiki user preferences. The MediaWiki attributes currently available are email, realname, nickname, and language. You can configure which MediaWiki preference maps to which AD attribute; put the following in your LocalSettings.php to retrieve preferences:

$wgLDAPPreferences = array( "TESTAD"=>array( "email"=>"mail","realname"=>"cn","nickname"=>"sAMAccountName","language"=>"preferredLanguage") );

Finding user and group DNs, and object attributes

To find the DN of a user in an AD group for use in any options mentioned above, use the dsquery command:

dsquery group -name "wiki-users"
"cn=wiki-users,ou=groups,dc=testad,dc=example,dc=com"

To get the value of specific attributes, use the dsquery command in conjunction with the dsget command:

dsquery user -name "test-user"
"cn=test-user,ou=Domain Users,dc=testad,dc=example,dc=com"
dsget "cn=test-user,ou=Domain Users,dc=testad,dc=example,dc=com" -upn
  upn
  test-user@TESTAD.EXAMPLE.COM

You can get a lot of information with these commands; to find out what else you can find, see the help documentation using dsquery /?.

Test your configuration by logging in with an LDAP user

If you are doing group synchronization, you should ensure users are being correctly added and removed from MediaWiki groups when they are being added and removed from your AD groups. If you are retrieving preferences, you should ensure they are being updated when you log in.

If you have any questions, you should post them on the discussion page for the plugin on mediawiki.org, or leave me a comment (the former is preferred).

The dsadm list-certs -C command will show you what CA certificates you are trusting, but it won’t show you how it is trusting a certificate. If you are getting an error like “Bind failed with response: Failed to bind to remote (900).”, and you know SSL should be working properly, you probably want to check to see exactly how your CA certificates are being trusted.

To do this, use the certutil command:

certutil -L -d /var/opt/SUNWdsee/dsins1/alias -P slapd-

The trust should show as “CT,,”. If it is showing as “c,c,c” or pretty much anything else, your CA certificate isn’t trusted properly. You can remove the  certificate and re-add it using certutil in the following ways:

certutil  -D -n "<your CA cert's alias>" -P slapd- -d /var/opt/SUNWdsee/dsins1/alias
certutil  -A -n "<your CA cert's alias>" -P slapd- -d /var/opt/SUNWdsee/dsins1/alias -i <location of your CA cert> -a

Now restart your directory server, and test replication. If you are lucky, this is your problem.

So, if you wanted to have a wiki, like a wiki for polls, that needed some form of anonymity for users to trust using it, using the LDAP Authentication extension in a clever way can allow you to do this.

Enable the extension and test authentication

First and foremost, you should ensure that LDAP authentication is configured and working properly; see part 1 and part 2 of the series of articles for using the LDAP plugin for MediaWiki.

Configure the SetUsernameAttributeFromLDAP hook

The LDAP extension has a configuration hook that allows you to set the username used in MediaWiki to any of the user’s attributes in LDAP. We’ll use this to create a semi-anonymous username based off one of the user’s attributes.

Notice that I am saying semi-anonymous for a reason. Unless you want to create a new user for someone every time they log in, you have to create the username in such a way that it is the same every time. Put the following into the bottom of LocalSettings.php:

// This hook is called by the LdapAuthentication plugin. It is a configuration hook. Here we
// are specifying what attibute we want to use for a username in the wiki.
// The hook calls the function defined below.
$wgHooks['SetUsernameAttributeFromLDAP'][] = 'SetUsernameAttribute';

// This function allows you to get the username from LDAP however you need to do it.
function SetUsernameAttribute(&$LDAPUsername, $info) {
    $LDAPUsername = $info[0]['cn'][0];
    $LDAPUsername = $LDAPUsername . "MySuperSecretAppendedString0230932740982738khewfjkshd";
    // How usernames are created should not be disclosed, otherwise
    // the psuedo-anonymity will be lost.
    $LDAPUsername = 'pseudo.' . md5($LDAPUsername);

    // All hooks have to return a boolean in MediaWiki
    return true;
}

You should change the attribute pulled, the “MySuperSecret…” string, and (possibly) the hashing function to something else. You should probably leave the “pseudo.” string alone. Notice that it is important that whatever hash function you use creates a username that is allowed by MediaWiki; I am using md5 above for this reason.

As you can see, the wiki system administrator, and anyone else that knows how you are hashing the usernames, can figure out who anonymous users are. It is important to keep this information secret.

Test login to ensure the username gets hashed

When you log in, you should have a semi-anonymous username. Log out and log in again; you should have the same semi-anonymous username; if not, your hashing function isn’t working properly.

Give your semi-anonymous user admin privileges

Notice that every user, including your admin user, is now semi-anonymous. Unfortunately, this means you are no longer an admin. To fix this:

1. Log out
2. Disable the semi-anonymous configuration
3. Log in as your admin user
4. Give admin privileges to your new semi-anonymous user
5. (Optionally) merge your old admin user with your new semi-anonymous user

I should probably mention that your admin user will likely no longer be anonymous after giving yourself admin privileges (after all, most people probably know who the wiki admin is).

An alternative to these steps is to not hash your admin’s username in the above function.

Feedback

Let me know if this is or isn’t working for you, or if you have a better way of making users anonymous.

Update (06/29/2009): Looks like this isn’t working right now unless you are using auto-authentication. I’ll try to have an update for the LDAP extension soon that’ll address this.

For basic password authentication against an LDAP domain with the posix schema, you need to configure three or four things:

1. Domain name
2. Server names
3. How to bind to the LDAP servers
4. The proxy user used to find your user accounts (optional depending on your environment)

Prerequisites

Please see and complete the “Create a local sysop”, and “Enabling the plugin” sections of part 1 before proceeding.

Configuring the plugin

Setting the domain name

The domain name is used for all of the LDAP configuration settings, and is also the domain name visible to users when logging in. It is recommended to use the short name of your LDAP domain as the domain name. For example, if your LDAP domain is testposix.example.com, then you should use testposix as your domain name. We will use testposix for the examples in this post.

Place the following in LocalSettings.php file to set the domain name:

$wgLDAPDomainNames = array( "testposix" );

Setting the server names

The plugin needs to know the fully qualified domain name (FQDN) of each of your LDAP servers to contact. You may add multiple servers, delimited by spaces, for server failover.

Place the following in LocalSettings.php to set the server names:

$wgLDAPServerNames = array( "testposix" => "ldapserver1.testposix.example.com ldapserver2.testposix.example.com" );

Telling the plugin how to bind to the LDAP server

Binding to the LDAP server can be straightforward if your Directory Information Tree (DIT) is simple; by simple, I mean your users are in ou=people, and they all have the same naming attribute (such as uid). To bind to this type of DIT, you simply need a bind DN format, and a password. You can tell the plugin to create the bind dn by adding the following in LocalSettings.php:

$wgLDAPSearchStrings = array( "testposix" => "uid=USER-NAME,ou=people,dc=testposix,dc=example,dc=com";

Notice that USER-NAME is a special string, and should not be modified. When the user logs in, USER-NAME will be replaced with whatever username is used.

If your DIT is not flat, or your naming attributes aren’t the same for all users, you’ll need to configure the plugin to first find the user’s DN, then bind as that user. To do this, you’ll need a search attribute, a base DN, and optionally a proxy agent and proxy agent password.

Your search attribute must be an attribute that all users share, and should preferably be a unique attribute; we’ll use uid for this. Your base DN must be at a node in your tree that is a parent to all of your users; we’ll use dc=testposix,dc=example,dc=com for this (the root DN). If your directory server allows users to be searched anonymously (which is abnormal), you don’t need to specify and proxy agent or proxy agent password. If your directory server requires authenticated searches (normal), you can specify a proxy agent and proxy agent password; we’ll use cn=proxyagent,ou=profile,dc=testposix,dc=example,dc=com and “T3stP0$ixP@$$” for this. Notice that you should give the bare minimum privileges needed to the proxy agent!

You can set these options by placing the following into LocalSettings.php:

$wgLDAPSearchAttributes = array( "testposix" => "uid" );
$wgLDAPBaseDNs = array( "testposix" => "dc=testposix,dc=example,dc=com" );
$wgLDAPProxyAgent = array( "testposix" => "cn=proxyagent,ou=profile,dc=testposix,dc=example,dc=com" );
$wgLDAPProxyAgentPassword = array( "testposix" => "T3stP0$ixP@$$" );

By default the LDAP plugin is set to bind using encryption. Specifically, the plugin defaults to tls using LDAP (port 389). The supported encryption types are clear, tls, and ssl. Most posix LDAP servers support TLS and SSL. It is recommended to keep encryption enabled. If you need to switch encryption types, you can use the following option in LocalSettings.php:

$wgLDAPEncryptionType = array( "testposix" => "ssl" );

Configuring the server

Configuring the SSL trust

For ssl to work properly, it is important to ensure the LDAP client (the web server) trusts the root Certificate Authority (CA) of the LDAP server. If your organization is using a third party CA that is in most normal trust lists (like in IE or Firefox), this step can likely be skipped. If your LDAP servers are using self signed certificates or a local CA, this step is needed.

You can find out which CA issued the LDAP server’s certificate using openssl. Run the following command:

openssl s_client -connect ldapserver1.testposix.example.com:636 | egrep "subject|issuer"

If the subject and the issuer are the same, the certificate is self signed. If the subject and issuer are not the same, the certificate was signed by a CA. If the CA is local, ask someone in your organization for a copy of the CA certificate. If the certificate is self signed, you can get the certificate by running the previous command without the grep:

openssl s_client -connect ldapserver1.testposix.example.com:636

Copy everything in between, and including:

-----BEGIN CERTIFICATE-----

and:

-----END CERTIFICATE-----

Paste the text into a file, and place the file wherever your OS normally stores its CA certificates; Red Hat Enterprise Linux 5 and newer versions of Fedora place these in /etc/pki/tls/certs.

Now place the following into /etc/openldap/ldap.conf:

TLS_CACERT     <pathToCACert>
TLS_CACERTFILE <pathToCACert>

Restart your web server for this to take effect.

Test your configuration by logging in with an LDAP user

Everything should be working at this point. If you have any questions, you should post them on the discussion page for the plugin on mediawiki.org, or leave me a comment (the former is preferred).